> For the complete documentation index, see [llms.txt](https://docs.nexthink.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexthink.com/api/nql/execute-an-nql.md).

# Execute an NQL

Execute NQL queries and retrieve data in JSON or CSV format

## Execute an NQL V1

> Executes an NQL query and returns the results.

```json
{"openapi":"3.0.1","info":{"title":"NQL API","version":"1.2.0"},"tags":[{"name":"Execute"}],"servers":[{"url":"https://instance.api.region.nexthink.cloud"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"NqlApiExecuteRequest":{"required":["queryId"],"type":"object","properties":{"queryId":{"maxLength":255,"minLength":1,"pattern":"^#[a-z0-9_]{2,255}$","type":"string","description":"Identifier of the query which is going to be executed."},"parameters":{"type":"object","additionalProperties":{"type":"string"},"description":"Key and value of the parameters to be replaced within the NQL query in order to compose a final query for execution. Example: {\\\"alert_name\\\": \\\"my_alert\\\", \\\"alert_status\\\": \\\"Open\\\"}\""}}},"NqlApiExecuteResponse":{"type":"object","properties":{"queryId":{"type":"string","description":"Identifier of the executed query"},"executedQuery":{"type":"string","description":"Final query executed with the replaced parameters."},"rows":{"type":"integer","description":"Number of rows returned","format":"int64"},"executionDateTime":{"allOf":[{"$ref":"#/components/schemas/DateTime"},{"type":"object","description":"Date and time of the execution"}]},"headers":{"type":"array","description":"Ordered list with the headers of the returned fields.","items":{"type":"string"}},"data":{"type":"array","description":"List of rows with the data returned by the query execution.","items":{"type":"array","items":{"type":"object"}}}}},"DateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int64"},"month":{"type":"integer","format":"int64"},"day":{"type":"integer","format":"int64"},"hour":{"type":"integer","format":"int64"},"minute":{"type":"integer","format":"int64"},"second":{"type":"integer","format":"int64"}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string","description":"Message with the description of the error."},"code":{"type":"integer","description":"Error code","format":"int32"},"source":{"type":"string","description":"Source of the error, if any."}}}}},"paths":{"/api/v1/nql/execute":{"post":{"tags":["Execute"],"summary":"Execute an NQL V1","description":"Executes an NQL query and returns the results.","operationId":"execute","parameters":[{"name":"Authorization","in":"header","schema":{"type":"string","nullable":false}},{"name":"Accept","description":"Set the header to `application/json` for a JSON response or `text/csv` for a CSV response. If no value is set, `application/json` applied by default. Otherwise, 406 error (not acceptable) is returned.","in":"header","schema":{"type":"string","nullable":true}},{"name":"x-utc-times","description":"Set the header to `true` for UTC timezone. With any other value, regional timezone is applied by default.","in":"header","schema":{"type":"string","nullable":true}},{"name":"x-platform-log-custom-tag","description":"Optional free-text tag, up to 255 characters, that can be added to the request. Nexthink stores the tag in the platform logs. The tag helps to categorize requests, and to filter and analyze them in logs and in dashboards. If the tag is longer than 255 characters, a 400 error is returned.","in":"header","schema":{"type":"string","nullable":true,"maxLength":255}}],"requestBody":{"description":"The configuration of the execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NqlApiExecuteRequest"}}},"required":true},"responses":{"200":{"description":"OK - Successful execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NqlApiExecuteResponse"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Bad request - Including a query that timed out because it was too expensive to run within the time budget, or the `x-platform-log-custom-tag` header is longer than 255 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - No valid authentication credentials."},"403":{"description":"No permission - Not authorized to execute queries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - No query associated with that ID."},"406":{"description":"Not Acceptable. The Accept header should be \"application/json\", \"text/csv\" or empty."},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable."}}}}}}
```

## Execute an NQL V2

> Executes an NQL query and returns the results.

```json
{"openapi":"3.0.1","info":{"title":"NQL API","version":"1.2.0"},"tags":[{"name":"Execute"}],"servers":[{"url":"https://instance.api.region.nexthink.cloud"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"NqlApiExecuteRequest":{"required":["queryId"],"type":"object","properties":{"queryId":{"maxLength":255,"minLength":1,"pattern":"^#[a-z0-9_]{2,255}$","type":"string","description":"Identifier of the query which is going to be executed."},"parameters":{"type":"object","additionalProperties":{"type":"string"},"description":"Key and value of the parameters to be replaced within the NQL query in order to compose a final query for execution. Example: {\\\"alert_name\\\": \\\"my_alert\\\", \\\"alert_status\\\": \\\"Open\\\"}\""}}},"NqlApiExecuteV2Response":{"type":"object","properties":{"queryId":{"type":"string","description":"Identifier of the executed query"},"executedQuery":{"type":"string","description":"Final query executed with the parameters replaced"},"rows":{"type":"integer","description":"Number of rows returned","format":"int64"},"executionDateTime":{"type":"string","description":"Date and time of the execution in ISO format"},"data":{"type":"array","description":"List of rows with the data returned by the query execution","items":{"type":"object","properties":{"key1":{},"key2":{}}}}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string","description":"Message with the description of the error."},"code":{"type":"integer","description":"Error code","format":"int32"},"source":{"type":"string","description":"Source of the error, if any."}}}}},"paths":{"/api/v2/nql/execute":{"post":{"tags":["Execute"],"summary":"Execute an NQL V2","description":"Executes an NQL query and returns the results.","operationId":"execute","parameters":[{"name":"Authorization","in":"header","schema":{"type":"string","nullable":false}},{"name":"Accept","description":"Set the header to `application/json` for a response or `text/csv` for a CSV response. If no value is set, `application/json` is applied by default. Otherwise, 406 error (not acceptable) is returned.","in":"header","schema":{"type":"string","nullable":true}},{"name":"x-utc-times","description":"Set the header to `true` for UTC timezone. With any other value, regional timezone is applied by default.","in":"header","schema":{"type":"string","nullable":true}},{"name":"x-platform-log-custom-tag","description":"Optional free-text tag, up to 255 characters, that can be added to the request. Nexthink stores the tag in the platform logs. The tag helps to categorize requests, and to filter and analyze them in logs and in dashboards. If the tag is longer than 255 characters, a 400 error is returned.","in":"header","schema":{"type":"string","nullable":true,"maxLength":255}}],"requestBody":{"description":"The configuration of the execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NqlApiExecuteRequest"}}},"required":true},"responses":{"200":{"description":"OK - Successful execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NqlApiExecuteV2Response"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Bad request - Including a query that timed out because it was too expensive to run within the time budget, or the `x-platform-log-custom-tag` header is longer than 255 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - No valid authentication credentials."},"403":{"description":"No permission - Not authorized to execute queries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - No query associated with that ID"},"406":{"description":"Not Acceptable - The accept header should be \"application/json\", \"text/csv\" or empty"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexthink.com/api/nql/execute-an-nql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.