> For the complete documentation index, see [llms.txt](https://docs.nexthink.com/api/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"}}}}}}
```