Skip to content

gRPC API queries

Overview

Using gRPC offers several advantages for developers building high-performance integrations. Because gRPC relies on Protocol Buffers (Protobuf) instead of JSON, requests and responses are transmitted in a compact binary format. This results in smaller payloads, faster serialization and deserialization, and lower CPU and memory overhead compared to traditional HTTP/JSON APIs. The result: reduced latency, higher throughput, and more efficient use of network resources.

Requirements

To make gRPC API calls, you’ll need a tool like grpcurl. You can install grpcurl or use any tool of your choice, but all of the examples below use grpcurl.

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.

Any request that lacks proper authentication will be rejected. 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.

Use the DataPrime endpoint that matches your Coralogix domain.

A typical gRPC API call is formatted like this: grpcurl -H "Authorization: <cx_api_key>" -d "<data_json_object>" <host_name> <grpc_method>

Request payload body

When making a POST request, structure your payload using the format shown below. The query field is required; all other fields are optional and can be included in the metadata object to control execution parameters such as time range, query tier, or default source.

Note

Background queries require more fields than just query. See background queries below.

The following example consists of a JSON structure that represents the request:

{
  "query": "source logs | limit 100",
  "metadata": {                              // optional
    "tier": "TIER_FREQUENT_SEARCH",          // TIER_ARCHIVE for long term storage
    "syntax": "QUERY_SYNTAX_DATAPRIME",      // QUERY_SYNTAX_LUCENE for Lucene queries
    "start_date": "2023-05-29T11:20:00.00Z",  // UTC
    "end_date": "2023-05-29T11:30:00.00Z",    // UTC
    "defaultSource": "logs"
  }
}

Note

While the examples above are labeled as JSON for readability, they are not true JSON payloads. When using tools like grpcurl, these structures are parsed and converted into Protobuf’s binary format under the hood. The JSON-like syntax is a convenience for human readability and documentation purposes only.

Direct API query

com.coralogixapis.dataprime.v1.DataprimeQueryService/Query

Warning

ng-api-grpc. is deprecated and should not be used

message Query {
    string query = 1;
}

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

Note

Protobuf key-value pairs are less descriptive than those in JSON documents because the keys are represented by numeric tags instead of human-readable names.

Make the API call

grpcurl -H "Authorization: <cx_api_key>" \
    -d '{ "query": "source logs | limit 10", "metadata": { "syntax": "QUERY_SYNTAX_DATAPRIME" }}' \
    api.<span class="domain-value"></span>:443 \
    com.coralogixapis.dataprime.v1.DataprimeQueryService/Query

Response

gRPC responses are streamed as binary data and may arrive in multiple messages instead of a single response object, as in REST. For background queries, the server sends the queryId first to acknowledge receipt, followed by a separate message containing the actual result data. These parts are logically connected but delivered in sequence over the stream. In most tools, such as grpcurl, these streamed messages are printed as separate JSON blocks.

{
  "queryId": {
    "queryId": "a1e02902-9ecf-490d-8b3f-ce9dba179e04"
  }
}
{
  "result": {
    "results": [
      {
        "metadata": [
          ...
        ],
        "labels": [
          ...
        ],
        "userData": ...
      },
      ...
    ]
  }
}

Background queries gRPC API overview

The Background queries gRPC API enables you to run high-latency, long-running queries asynchronously using DataPrime or Lucene syntax from scripts or the CLI. Designed for recurring, extensive analytical tasks—such as monthly or quarterly reports—this API allows you to offload complex queries to run in the background, freeing you to continue real-time monitoring within the Coralogix platform.

Use it to:

  • Seamlessly query archived logs and spans, regardless of time range.
  • Leverage higher scan, file, and shuffle limits for deeper data access.
  • Take advantage of extended execution times for heavy analytical workloads.

The API supports the following background gRPCs:

Note

The structure of background query requests are different from that of direct query requests, specifically that background query requests don't contain the matadata nested object.

SubmitBackgroundQuery

com.coralogixapis.dataprime.v1.DataprimeQueryService/SubmitBackgroundQuery

message SubmitBackgroundQueryRequest {
  google.protobuf.StringValue query = 1;
  com.coralogixapis.dataprime.v1.QuerySyntax syntax = 2;
  // Start of query time range (inclusive)
  optional google.protobuf.Timestamp start_date = 3;
  // End of query time range (exclusive)
  optional google.protobuf.Timestamp end_date = 4;
  // Used by functions like now() in DataPrime
  optional google.protobuf.Timestamp now_date = 5;
}

{
  "query": "limit 3", 
  "syntax":"QUERY_SYNTAX_DATAPRIME", 
  "start_date": "2024-01-20T00:00:00Z", 
  "end_date": "2024-01-20T01:00:00Z", 
  "now_date":"2024-01-20T02:00:00Z"
  }

Make the API call

 grpcurl -H "Authorization: <cx_api_key>" \
    -d '{ "query": "limit 3", "syntax":"QUERY_SYNTAX_DATAPRIME", "start_date": "2024-01-20T00:00:00Z", "end_date": "2024-01-20T01:00:00Z", "now_date":"2024-01-20T02:00:00Z"}' \
    api.<span class="domain-value"></span>:443 \
    com.coralogixapis.dataprime.v1.DataprimeQueryService/SubmitBackgroundQuery

Response

The response object contains a queryId. This ID is used to do follow up operations on the background query.

{
  "queryId": "1712b991-b9be-455f-944e-308f6aa6bbbe"
}

GetBackgroundQueryStatus

com.coralogixapis.dataprime.v1.DataprimeQueryService/GetBackgroundQueryStatus

message GetBackgroundQueryStatusRequest {
  // Generated query ID that can be later used to obtain status and results
  string query_id = 1;
}

{ 
  "query_id": "412036c3-04be-431a-b1e2-9ebf971be6c6" 
}

Make the API call

grpcurl -H "Authorization: <cx_api_key>" \
    -d '{ "query_id": "412036c3-04be-431a-b1e2-9ebf971be6c6" }' \
    api.<span class="domain-value"></span>:443 \
    com.coralogixapis.dataprime.v1.DataprimeQueryService/GetBackgroundQueryStatus

Response

{
  "terminated": {
    "runningSince": "2025-01-21T09:35:01Z",
    "terminatedAt": "2025-01-21T09:35:01Z",
    "success": {}
  },
  "submittedAt": "2025-01-21T09:35:00Z",
  "metadata": [
    {
      "statistics": {
        "bytesScanned": "506070"
      }
    }
  ]
}

CancelBackgroundQuery

com.coralogixapis.dataprime.v1.DataprimeQueryService/CancelBackgroundQuery

message CancelBackgroundQueryRequest {
  // Generated query ID that can be later used to obtain status and results
  string query_id = 1;
}

{
  "query_id": "412036c3-04be-431a-b1e2-9ebf971be6c6"
}

Make the API call

grpcurl -H "Authorization: <cx_api_key>" \
    -d '{ "query_id": "412036c3-04be-431a-b1e2-9ebf971be6c6" }' \
    api.<span class="domain-value"></span>:443 \
    com.coralogixapis.dataprime.v1.DataprimeQueryService/CancelBackgroundQuery

Response

{}

GetBackgroundQueryData

com.coralogixapis.dataprime.v1.DataprimeQueryService/GetBackgroundQueryData

message GetBackgroundQueryDataRequest {
  // Generated query ID that can be later used to obtain status and results
  string query_id = 1;
}

{
  "query_id": "412036c3-04be-431a-b1e2-9ebf971be6c6"
}

Make the API call

grpcurl -H "Authorization: <cx_api_key>" \
    -d '{ "query_id": "412036c3-04be-431a-b1e2-9ebf971be6c6" }' \
    api.<span class="domain-value"></span>:443 \
    com.coralogixapis.dataprime.v1.DataprimeQueryService/GetBackgroundQueryData

Response

{
  "queryId": {
    "queryId": "a1e02902-9ecf-490d-8b3f-ce9dba179e04" // initial acknowledgment
  }
}
{
  "result": {  // returned later via streaming
    "results": [
      {
        "metadata": [
          ...
        ],
        "labels": [
          ...
        ],
        "userData": ...
      },
      ...
    ]
  }
}

Response handling

gRPC APIs use standard gRPC status codes instead of traditional HTTP response codes. When a request fails, the response will include one of the following codes, along with a descriptive error message.
Status codeDescription
OKThe request was successful.
INVALID_ARGUMENTThe request was malformed — e.g., a required field was missing or misformatted.
UNAUTHENTICATEDThe API key is missing or invalid.
PERMISSION_DENIEDThe API key is valid but lacks the required permissions.
NOT_FOUNDThe specified queryId does not exist or has expired.

A response with INVALID_ARGUMENT usually indicates that the request body doesn't follow the expected schema or contains invalid enum values or date formats.

If you receive UNAUTHENTICATED or PERMISSION_DENIED, check your API keys page or contact your workspace administrator to ensure you have the correct credentials and permissions.

Limitations

When a limit is breached, a warning message is displayed.

See the limitations page for a comprehensive list of limitations.

Previous Previous HTTP API queries
Next Quoting JSON in shell scripts for API requests Next
Home
User Guides User Guides
DataPrime DataPrime
Integrations Integrations
OpenTelemetry OpenTelemetry
Developer Portal Developer Portal