Skip to content

Requests

API queries are made using JSON over HTTPS (referred to here as HTTP requests). All requests must use HTTPS. Calls made over plain HTTP will fail. Additionally, any request that lacks proper authentication will be rejected.

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.
KeyAuthorization
ValueBearer <cx_api_key>

Requests

Note

When working with curl or similar command-line tools to make JSON over HTTP API requests, it's important to understand how your shell (typically Bash) processes quotes inside command arguments. This becomes especially relevant when your request payload includes JSON — and even more so when the JSON contains both single and double quotes. Find out more here.

Host

Use the DataPrime endpoint that matches your Coralogix domain.

Authorization header

You must provide an authorization header as described in Authentication.

Formatting your request

For complete guidance on how to structure 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.

Body examples

The following example consists of a JSON object that represents the request

Minimal DataPrime query

{
  "query": "source logs | limit 100"
}

DataPrime with Lucene operator

{
  "query": "source logs | filter log_obj.subsystem_name == 'foo' | lucene 'coralogix.metadata.applicationName:bar'"
}

Lucene query

{
  "query": "coralogix.metadata.applicationName:bar'",
  "metadata": {
    "syntax": "QUERY_SYNTAX_LUCENE"
  }
}

Full DataPrime query

{
  "query": "source logs | limit 100",
  "metadata": {
    "tier": "TIER_FREQUENT_SEARCH",
    "syntax": "QUERY_SYNTAX_DATAPRIME",
    "startDate": "2023-05-29T11:20:00.00Z",
    "endDate": "2023-05-29T11:30:00.00Z",
    "defaultSource": "logs"
  }
}

cURL

Basic usage

curl --location 'https://ng-api-http.<span class="domain-value"></span>/api/v1/dataprime/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <cx_api_key>' \
--data '{
    "query": "source logs | limit 10"
}'

With metadata

curl --location 'https://ng-api-http.<span class="domain-value"></span>/api/v1/dataprime/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <cx_api_key>' \
--data '{
    "query": "source logs | limit 10",
    "metadata": {
        "tier": "TIER_FREQUENT_SEARCH",
        "syntax": "QUERY_SYNTAX_DATAPRIME",
        "startDate": "2023-05-29T11:20:00.00Z",
        "endDate": "2023-05-29T11:30:00.00Z"
    }
}'
  • 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.

Use TIER_FREQUENT_SEARCH for querying frequently accessed logs (default). To retrieve logs from long-term storage, TIER_ARCHIVE must be specified.

  • limit : The maximum number of results to return. The default is 2000, with a maximum of 12,000.

  • syntax: The query syntax to use. Options are QUERY_SYNTAX_DATAPRIME or QUERY_SYNTAX_LUCENE.

With defaultSource

curl --location 'https://ng-api-http.<span class="domain-value"></span>/api/v1/dataprime/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <cx_api_key>' \
--data '{
    "query": "limit 10",
    "metadata": {
        "tier": "TIER_FREQUENT_SEARCH",
        "syntax": "QUERY_SYNTAX_DATAPRIME",
        "defaultSource": "logs"
    }
}'

Note

When querying archived logs using the API, you must explicitly specify "tier": "TIER_ARCHIVE" in the metadata object of your request. Otherwise, the default is "tier": "TIER_FREQUENT_SEARCH".

Responses

The Content-Type representation header is used to indicate the original media type of the resource (before any content encoding is applied for sending).

In responses, a Content-Type header provides the client with the actual content type of the returned content.

Correct results are returned in batches. Each batch may contain multiple rows of results, which are returned as Newline Delimited JSON or ndjson format.

Example response

The response will consist of 2 JSON objects. The first will contain the queryId and the second will contain the result of the DataPrime query.

{
    "queryId": {
        "queryId": "12345678-07f8-4313-1234-d954b1b45d31"
    }
}
{
    "result": {
        "results": [
            {
                "metadata": [
                    {
                        "key": "logid",
                        "value": "c3ca5343-88dc-4807-a8f3-82832274afb7"
                    }
                ],
                "labels": [
                    {
                        "key": "applicationname",
                        "value": "staging"
                    }
                ],
                "userData": "{ ... \"log_obj\":{\"level\":\"INFO\",\"message\":\"some log message\" ... }, ...}"
            }
        ]
    }
}

Background queries HTTP API

The Background Queries JSON over 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.

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"
}
FieldDescriptionExample
startDateThe 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
endDateThe 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.
tierSpecifies the tier of data to query. Options are TIER_FREQUENT_SEARCH or TIER_ARCHIVE.TIER_FREQUENT_SEARCH
limitThe maximum number of results to return. The default is 2000, with a maximum determined by the data tier2000
syntaxThe 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": "..."
        },
        ...
      ]
    }
  }
},
{
  ...
}
...

Status codes

Here are some of the most common status codes to expect.
Status CodeDescription
200No Error
400Bad Request
403Forbidden

Failed requests

The general format guidelines are displayed when the accompanying status code is returned.

Warnings

The Warning response contains information about possible problems with the status of the message. More than one Warning header may appear in a response.

Warning responses can be applied to any message, before or after query results.
Warning typeDescription
CompileWarningWarning of potential compilation error in your query. In the event of a compilation failure, you will receive an error response.
TimeRangeWarningWhen the time frame for your query has been built incorrectly or exceeds internal limits
NumberOfResultsLimitWarningWhen the number of query results exceeds internal limits
BytesScannedLimitWarningWhen the number of bytes returned in query results exceeds internal limits
DeprecationWarningWhen a value in your query is changed or deprecated incorrectly

Limitations

Coralogix places certain limitations on query responses. Warnings are returned when a limit is breached.

Previous Previous API queries
Next gRPC API Queries Next
Home
User Guides User Guides
DataPrime DataPrime
Integrations Integrations
OpenTelemetry OpenTelemetry
Developer Portal Developer Portal