Background Queries HTTP API
The Background Queries HTTP API enables you to run high-latency, long-running queries asynchronously using DataPrime or Lucene syntax from scripts or CLI. Ideal for recurring, extensive analytical tasks—such as monthly or quarterly reports—this feature operates in the background, allowing you to continue active monitoring within the Coralogix platform.
Use it to:
- Seamlessly query archived logs and spans, regardless of daily quota or time frame.
- Leverage larger scan, file, and shuffle limits for comprehensive data retrieval.
- Benefit from extended execution times for running complex queries.
API reference
This documentation outlines the API using an HTTP-style method. Documentation for the gRPC-style method can be found here.
Our API has predictable resource-oriented URLs, accepts POST JSON-formatted request bodies, returns Newline Delimited or NDJSON-formatted responses, and uses standard HTTP response codes, authentication, and verbs.
Prerequisites
Requests must be sent using TLS.
Base URL
Use the DataPrime endpoint that matches your Coralogix domain.
When sending an HTTPS POST, you must present your arguments as JSON.
HTTP Method | POST |
---|---|
Content-Type | JSON |
Authentication
API key
To use this API you need to create a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.
Preset | Action | Description |
---|---|---|
DataQuerying | LEGACY-ARCHIVE-QUERIES:EXECUTE |
Query Data from the Archive |
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Authorization header
To authenticate, add an Authorization Bearer <cx_api_key>
header to your API request. It contains a Bearer Token, which identifies a single user, bot user, or workspace-application relationship for authentication.
Key | Authorization |
---|---|
Value | Bearer <cx_api_key> |
Requests
Host
Use the DataPrime endpoint that matches your Coralogix domain.
All requests must be made over HTTPS. The API does not support HTTP.
Authorization header
You must provide an authorization header as described in Authentication.
Formatting your request
For complete guidance on structuring requests and responses, view this swagger.md, a human-readable document derived from a swagger.json file.
We recommend using OpenAPI Editor or a similar technology for support.
Request body
When submitting data to a resource via POST
, you must submit your payload in JSON.
You are required to include a query
in the API body.
All other fields are optional and form the metadata object.
Note
Include a limit field in both the query and request body to increase the number of results beyond the default 2,000, up to the maximum limit allowed for the query tier.
Body examples
The following example consists of a JSON object that represents the request.
POST /api/v1/dataprime/background-query
{
"query": "limit 101",
"syntax": "QUERY_SYNTAX_DATAPRIME",
"startDate": "2025-01-20T00:00:00Z",
"endDate": "2025-01-20T01:00:00Z",
"nowDate": "2025-01-20T02:00:00Z"
}
POST /api/v1/dataprime/background-query/status
POST /api/v1/dataprime/background-query/cancel
POST /api/v1/dataprime/background-query/data
Field | Description | Example |
---|---|---|
startDate |
The start date and time for the query.Assumes Coordinated Universal Time (UTC). If the time zone of your timestamp differs, convert it to UTC or offset the timestamp to your time zone by navigating to Account settings > Preferences > Change Your Time Zone Settings. | For example, to start the query at 11:20 local time: |
In San Francisco (Pacific Daylight Time): 2023-05-29T11:20:00.00-07:00 | ||
In India (India Standard Time): 2023-05-29T11:20:00.00+05:30 | ||
endDate |
The end date and time for the query.Assumes Coordinated Universal Time (UTC). If the time zone of your timestamp differs, convert it to UTC or offset the timestamp to your time zone by navigating to Account settings > Preferences > Change Your Time Zone Settings. | |
tier |
Specifies the tier of data to query. Options are TIER_FREQUENT_SEARCH or TIER_ARCHIVE . |
TIER_FREQUENT_SEARCH |
limit |
The maximum number of results to return. The default is 2000, with a maximum determined by the data tier | 2000 |
syntax |
The query syntax to use. Options are QUERY_SYNTAX_DATAPRIME or QUERY_SYNTAX_LUCENE . |
QUERY_SYNTAX_LUCENE |
Responses
The Content-Type
representation header indicates the original media type of the resource before any content encoding is applied for transmission.
In responses, the Content-Type
header informs the client of the actual content type of the returned data.
Data endpoint results are returned in batches, with each batch containing multiple rows formatted as Newline Delimited JSON (NDJSON). Other types of responses are returned in standard JSON format.
POST /api/v1/dataprime/background-query
POST /api/v1/dataprime/background-query/status
{
"terminated": {
"runningSince": "2025-01-23T15:16:01Z",
"terminatedAt": "2025-01-23T15:16:01Z",
"success": {}
},
"submittedAt": "2025-01-23T15:15:58Z",
"metadata": [
{
"statistics": {
"bytesScanned": "506070"
}
}
],
"warnings": []
}
POST /api/v1/dataprime/background-query/cancel
POST /api/v1/dataprime/background-query/data
{
"response": {
"results": {
"results": [
{
"metadata": [...],
"labels": [...],
"userData": "..."
},
...
]
}
}
}
{
...
}
...
Response handling
The APIs return standard responses using HTTP status codes. The supported status codes are as follows:
HTTP Code | Description | Method |
---|---|---|
200 OK |
Success | All Methods |
500 Internal Server Error |
Internal Server Error | All Methods |
401 Unauthorized |
Unauthorized | All Methods |
403 Forbidden |
Forbidden | All Methods |
400 Bad Request |
Invalid Rule Expression or ID Format | Block/Allow Method |
409 Conflict |
Metric Already Blocked | Block Method |
412 Precondition Failed |
Bad Request | Block Method |
Limitations
Background Query APIs are designed for extended operations and have the following limitations:
- Execution time: Queries are limited to a maximum execution time of 30 minutes, compared to 5 minutes in Explore.
- Data Latency: Results may take longer to process due to the extended time ranges and larger data scans supported by the API.
Support
Need help?
Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.
Feel free to reach out to us via our in-app chat or by sending us an email to [email protected].