# Execute an NQL

## 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}}],"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"}}}},"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}}],"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"}}}},"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: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.