> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/agentix-api/cortex-agentix/xql-query.md). # XQL Query Run XQL queries on your data sources using a series of APIs. ## Start an XQL query > Execute an XQL query.\ > \ > For more information on how to run XQL queries, see \[Run XQL Query APIs]\( > \ > \\ > \ > \> #### Note\ > \>\ > \> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\ > \ > Required license: \*\*Cortex AgentiX Enterprise\*\* or \*\*Cortex AgentiX Base\*\* ```json {"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"XQL query","description":"Run XQL queries on your data sources using a series of APIs."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/xql/start_xql_query":{"post":{"tags":["XQL query"],"summary":"Start an XQL query","description":"Execute an XQL query.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**","operationId":"postStartXqlQuery","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"query":{"type":"string","description":"String of the XQL query."},"tenants":{"type":"array","description":"Note: This is only used when querying tenants managed by Managed Security Services Providers (MSSP).\n\nList of strings used for running APIs on local and Managed Security tenants. Valid values:\n- For single tenant (local tenant) query, enter a single-item list with your tenant_id. Additional valid values are, empty list ([]) or null (default).\n- For multi-tenant investigations (Managed Security parent who investigate children and/or local), enter multi-item list with the required tenant_id. List of IDs can contain the parent, children, or both parent and children.","items":{"type":"string"}},"timeframe":{"type":"object","description":"Integer in timestamp epoch milliseconds.\r\nValid values include:\r\n- Absolute Unix timestamp representing a date period: {\"from\" : 1598907600000, \"to\" : 1599080399000} = date period: 31/08/20 09:00:00 PM UTC - 02/09/20 8:59:59 PM UTC\r\n- Relative Unix timestamp representing the last 24 hours: {\"relativeTime\": 86400000} = (24 * 60 * 60 * 1000 = 86400000).","properties":{"from":{"type":"integer","description":"Use for an absolute timeframe in Unix timestamp."},"to":{"type":"integer","description":"Use for an absolute timeframe in Unix timestamp."},"relativeTime":{"type":"integer","description":"Use for a relative Unix timestamp."}}}},"required":["query"]}},"required":["request_data"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"string"}}}}}},"400":{"description":"Bad Request. Invalid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer"},"err_msg":{"type":"string"},"err_extra":{"type":"object","properties":{"err_msg":{"type":"string"},"query_cost":{"type":"integer"},"remaining_quota":{"type":"integer"},"total_daily_running_queries":{"type":"integer","description":"The number of daily active queries."},"total_daily_concurrent_rejected_queries":{"type":"integer","description":"The number of daily queries rejected due to too many concurrent XQL queries being run through the API."}}}}}}}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer"},"err_msg":{"type":"string"},"err_extra":{"type":"object","properties":{"err_msg":{"type":"string"},"query_cost":{"type":"integer"},"remaining_quota":{"type":"integer"},"total_daily_running_queries":{"type":"integer","description":"The number of daily active queries."},"total_daily_concurrent_rejected_queries":{"type":"integer","description":"The number of daily queries rejected due to too many concurrent XQL queries being run through the API."}}}}}}}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer"},"err_msg":{"type":"string"},"err_extra":{"type":"object","properties":{"err_msg":{"type":"string"},"query_cost":{"type":"integer"},"remaining_quota":{"type":"integer"},"total_daily_running_queries":{"type":"integer","description":"The number of daily active queries."},"total_daily_concurrent_rejected_queries":{"type":"integer","description":"The number of daily queries rejected due to too many concurrent XQL queries being run through the API."}}}}}}}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer"},"err_msg":{"type":"string"},"err_extra":{"type":"object","properties":{"err_msg":{"type":"string"},"query_cost":{"type":"integer"},"remaining_quota":{"type":"integer"},"total_daily_running_queries":{"type":"integer","description":"The number of daily active queries."},"total_daily_concurrent_rejected_queries":{"type":"integer","description":"The number of daily queries rejected due to too many concurrent XQL queries being run through the API."}}}}}}}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer"},"err_msg":{"type":"string"},"err_extra":{"type":"object","properties":{"err_msg":{"type":"string"},"query_cost":{"type":"integer"},"remaining_quota":{"type":"integer"},"total_daily_running_queries":{"type":"integer","description":"The number of daily active queries."},"total_daily_concurrent_rejected_queries":{"type":"integer","description":"The number of daily queries rejected due to too many concurrent XQL queries being run through the API."}}}}}}}}}}}}}}} ``` ## Get XQL query results > Retrieve results of an executed XQL query API. \ > \ > Note: This endpoint only works on XQL queries initiated by \`/public\_api/v1/xql/start\_xql\_query/\`.\ > \ > Maximum result set size is 1000. The API does not support pagination, therefore, you can set values to determine the result size limitation and how to wait for the results. To view response with greater than 1000 results you must call \[Get XQL query results Stream]\( > \ > For more information on how to run XQL queries, see \[Run XQL Query APIs]\( > \ > \\ > \ > \> #### Note\ > \>\ > \> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\ > \ > Required license: \*\*Cortex AgentiX Enterprise\*\* or \*\*Cortex AgentiX Base\*\* ```json {"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"XQL query","description":"Run XQL queries on your data sources using a series of APIs."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/xql/get_query_results":{"post":{"tags":["XQL query"],"summary":"Get XQL query results","description":"Retrieve results of an executed XQL query API. \n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nMaximum result set size is 1000. The API does not support pagination, therefore, you can set values to determine the result size limitation and how to wait for the results. To view response with greater than 1000 results you must call [Get XQL query results Stream](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/xql-query#post-public_api-v1-xql-get_query_results_stream).\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**","operationId":"postGetQueryResults","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"query_id":{"type":"string","description":"String representing the unique execution ID generated by the response to [Start an XQL query](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/xql-query#post-public_api-v1-xql-start_xql_query) API.\nYou can also enter the execution ID of a query generated in Cortex XDR and listed in the Query Center table."},"pending_flag":{"type":"boolean","description":"Boolean flag indicating whether the API call should operate in synchronous/blocking mode, or in asynchronous/non-blocking mode. Valid Values:\n- True (default): The call returns immediately with one of the following options:\n1) PENDING status indicating query hasn't yet completed or results are not yet ready to be returned. Need to execute the API call again.\n2) SUCCESS/FAIL status\n- False: The API will block until query completes and results are ready to be returned."},"limit":{"type":"integer","description":"Integer representing the maximum number of results to return.\nIf the 'limit' is not specified or if 'limit' is greater than 1000 and the query yields more than 1000 valid results, a `stream id` will be generated for use in the *Get XQL query results Stream** API.\nIn the context of multi-tenant investigations, when you specify the parameter value (x),\nit will return x results across all tenants combined, rather than x results for each individual tenant.\nFor example, if there are y tenants participating in the investigation, the maximum number of results returned can be x*y (up to the limit of 1,000,000)."},"format":{"type":"string","enum":["json","csv"],"description":"The type of response output."}},"required":["query_id"]}},"required":["request_data"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"status":{"type":"string"},"number_of_results":{"type":"integer"},"query_cost":{"type":"object","additionalProperties":{"type":"number"}},"remaining_quota":{"type":"number"},"results":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"event_id":{"type":"string"},"agent_version":{"type":"string"},"_product":{"type":"string"},"_time":{"type":"integer"},"_vendor":{"type":"string"},"insert_timestamp":{"type":"integer"},"agent_os_type":{"type":"string"},"event_type":{"type":"string"},"event_sub_type":{"type":"string"}}}}}}}}}}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"type":"object","title":"reply","description":"The query result upon error.","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}}}}}} ``` ## Get XQL query Quota > Retrieve the amount of query quota available and used. \ > \ > Note: This endpoint only works on XQL queries initiated by \`/public\_api/v1/xql/start\_xql\_query/\`.\ > \ > For more information on how to run XQL queries, see \[Run XQL Query APIs]\( > \ > \\ > \ > \> #### Note\ > \>\ > \> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\ > \ > Required license: \*\*Cortex AgentiX Enterprise\*\* or \*\*Cortex AgentiX Base\*\* ```json {"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"XQL query","description":"Run XQL queries on your data sources using a series of APIs."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/xql/get_quota":{"post":{"tags":["XQL query"],"summary":"Get XQL query Quota","description":"Retrieve the amount of query quota available and used. \n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**","operationId":"postGetQuota","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"license_quota":{"type":"integer"},"additional_purchased_quota":{"type":"integer"},"used_quota":{"type":"number"},"eval_quota":{"type":"integer"},"total_daily_running_queries":{"type":"integer","description":"The number of daily active queries. This value is reset nightly."},"total_daily_concurrent_rejected_queries":{"type":"integer","description":"The number of daily queries rejected due to too many concurrent XQL queries being run through the API. This value is reset nightly."},"current_concurrent_active_queries":{"type":"object","description":"Currently running XQL queries with their current duration.","additionalProperties":{"type":"string"}},"current_concurrent_active_queries_count":{"type":"integer","description":"The number of active queries currently running."},"max_daily_concurrent_active_query_count":{"type":"integer","description":"The maximum number of queries that ran concurrently today on this tenant. This value is reset nightly."}}}}}}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"object","properties":{"err_code":{"type":"integer"},"err_msg":{"type":"string"},"err_extra":{"type":"object","properties":{"err_msg":{"type":"string"},"query_cost":{"type":"integer"},"remaining_quota":{"type":"integer"},"total_daily_running_queries":{"type":"integer"},"total_daily_concurrent_rejected_queries":{"type":"integer"}}}}}}}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"type":"object","title":"reply","description":"The query result upon error.","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}}}}}} ``` ## Get XQL query results Stream > Retrieve XQL query results with more than 1000 results. \ > \ > Note: This endpoint only works on XQL queries initiated by \`/public\_api/v1/xql/start\_xql\_query/\`.\ > \ > Response is returned as chunked (Transfer-Encoding: chunked). To retrieve a compressed gzipped response (Content-Encoding: gzip), in your header add Accept-Encoding: gzip.\ > \ > For more information on how to run XQL queries, see \[Run XQL Query APIs]\( > \ > \\ > \ > \> #### Note\ > \>\ > \> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\ > \ > Required license: \*\*Cortex AgentiX Enterprise\*\* or \*\*Cortex AgentiX Base\*\* ```json {"openapi":"3.0.0","info":{"title":"Cortex AgentiX APIs","version":"Cortex AgentiX"},"tags":[{"name":"XQL query","description":"Run XQL queries on your data sources using a series of APIs."}],"servers":[{"url":"https://api-yourfqdn"}],"paths":{"/public_api/v1/xql/get_query_results_stream":{"post":{"tags":["XQL query"],"summary":"Get XQL query results Stream","description":"Retrieve XQL query results with more than 1000 results. \n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nResponse is returned as chunked (Transfer-Encoding: chunked). To retrieve a compressed gzipped response (Content-Encoding: gzip), in your header add Accept-Encoding: gzip.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**","operationId":"postGetQueryResultsStream","parameters":[{"name":"Authorization","in":"header","description":"{api_key}","required":true,"schema":{"type":"string"}},{"name":"x-xdr-auth-id","in":"header","description":"{api_key_id}","required":true,"schema":{"type":"string"}},{"name":"Accept-Encoding","in":"header","description":"For retrieving a compressed gzipped response","schema":{"type":"string","default":"gzip"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_data":{"type":"object","properties":{"stream_id":{"type":"string","description":"String representing the unique ID generate by the response to [Get XQL query results](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/xql-query#post-public_api-v1-xql-get_query_results) API."},"is_gzip_compressed":{"type":"boolean","description":"A boolean flag."}},"required":["stream_id"]}},"required":["request_data"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{}}},"400":{"description":"Bad Request. Got an invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"401":{"description":"Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"402":{"description":"Unauthorized access. User does not have the required license type to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"403":{"description":"Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}},"500":{"description":"Internal server error. A unified status for API communication type errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reply"}}}}}}}},"components":{"schemas":{"reply":{"type":"object","title":"reply","description":"The query result upon error.","properties":{"err_code":{"type":"string","description":"HTTP response code."},"err_msg":{"type":"string","description":"Error message."},"err_extra":{"type":"string","description":"Additional information describing the error."}}}}}} ``` --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/agentix-api/cortex-agentix/xql-query.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.