Skip to content

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.

Download swagger.json

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

{
    "queryId": "c80fa3e7-fa5b-441a-b0d4-acdbdbe36e64"
}

POST /api/v1/dataprime/background-query/cancel

{
    "queryId": "c80fa3e7-fa5b-441a-b0d4-acdbdbe36e64"
}

POST /api/v1/dataprime/background-query/data

{
    "queryId": "c80fa3e7-fa5b-441a-b0d4-acdbdbe36e64"
}
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

{
    "queryId": "a63653bc-aba8-49cf-b4a4-1b1ca9907f54",
    "warnings": []
}

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].