Coralogix Data Usage Query Service API

openapi: 3.2.0
info:
  title: Coralogix Management Data Usage Query Service API
  version: '5'
  description: 'Management API for the Coralogix observability platform. The base URL is region-specific: pick the `servers` entry matching your Coralogix domain. Authentication is a bearer API key.'
servers:
- url: https://api.eu1.coralogix.com/mgmt/openapi/5
- url: https://api.eu2.coralogix.com/mgmt/openapi/5
- url: https://api.us1.coralogix.com/mgmt/openapi/5
- url: https://api.us2.coralogix.com/mgmt/openapi/5
- url: https://api.us3.coralogix.com/mgmt/openapi/5
- url: https://api.ap1.coralogix.com/mgmt/openapi/5
- url: https://api.ap2.coralogix.com/mgmt/openapi/5
- url: https://api.ap3.coralogix.com/mgmt/openapi/5
- url: https://api.gov1.coralogixgov.us/mgmt/openapi/5
security:
- apiKeyAuth: []
tags:
- name: Data Usage Query Service
  description: Query billable data usage through the public Coralogix API using daily or hourly bucketed aggregations over supported labels.
paths:
  /dataplan/data-usage/v1/capabilities:
    get:
      description: 'Returns the labels, measurement kinds, units, and per-request limits supported by the public data-usage API in v1, so clients can validate queries before submitting them.


        Requires the following permissions:

        - `data-usage:Read`'
      operationId: DataUsageQueryService_GetDataUsageCapabilities
      responses:
        '200':
          content:
            application/json:
              example:
                maxFilterValues: 256
                maxFilters: 8
                maxGroupByLabels: 6
                maxUsageEntriesPerMessage: 1000
                supportedLabels:
                - highCardinality: false
                  key: feature_id
                  keyDescription: Coralogix feature identifier such as logs_ingestion.
                  knownValues:
                  - description: Log volume ingested.
                    value: logs_ingestion
                supportedMeasurements:
                - description: Bytes processed.
                  kind: MEASUREMENT_KIND_PROCESSED_DATA_SIZE
                  unit: MEASUREMENT_UNIT_BYTES
              schema:
                $ref: '#/components/schemas/GetDataUsageCapabilitiesResponse'
          description: ''
      summary: Get data usage capabilities
      tags:
      - Data Usage Query Service
      x-coralogixPermissions:
      - data-usage:Read
  /dataplan/data-usage/v1/query:
    post:
      description: 'Returns billable data usage aggregated into daily or hourly buckets. Supports filtering and grouping by labels listed by the capabilities endpoint.


        Requires the following permissions:

        - `data-usage:Read`'
      operationId: DataUsageQueryService_DataUsage
      requestBody:
        content:
          application/json:
            schema:
              description: Shared query payload used by both unary and streamed data-usage methods.
              oneOf:
              - required:
                - daily
                type: object
              - required:
                - hourly
                type: object
              - not:
                  anyOf:
                  - required:
                    - daily
                    type: object
                  - required:
                    - hourly
                    type: object
                type: object
              properties:
                daily:
                  $ref: '#/components/schemas/UsageDailyQuery'
                filters:
                  description: Label predicates applied before aggregation.
                  items:
                    $ref: '#/components/schemas/UsageLabelFilter'
                  maxItems: 16
                  minItems: 0
                  type: array
                groupBy:
                  allOf:
                  - $ref: '#/components/schemas/UsageGroupBy'
                  description: Label keys to group results by. Supported keys are listed by the capabilities endpoint.
                hourly:
                  $ref: '#/components/schemas/UsageHourlyQuery'
                limit:
                  allOf:
                  - $ref: '#/components/schemas/UsageLimit'
                  description: Per-bucket result-size cap. The server may reject queries whose pre-cap size still exceeds its hard limits.
                measurementKindFilter:
                  description: Measurement kind filter applied before aggregation. Omit (or pass an empty list) to include all supported measurement kinds.
                  items:
                    $ref: '#/components/schemas/UsageMeasurementKind'
                  maxItems: 8
                  minItems: 0
                  type: array
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                buckets:
                - entries:
                  - labels:
                    - key: feature_id
                      value: logs_ingestion
                    measurements:
                    - cxQuotaUnits:
                        value: '1.5'
                      kind: MEASUREMENT_KIND_PROCESSED_DATA_SIZE
                      measuredUnit: MEASUREMENT_UNIT_BYTES
                      measuredValue: '1073741824'
                  range:
                    end: '2026-06-02T00:00:00.000Z'
                    start: '2026-06-01T00:00:00.000Z'
                queryRange:
                  end: '2026-06-08T00:00:00.000Z'
                  start: '2026-06-01T00:00:00.000Z'
              schema:
                $ref: '#/components/schemas/DataUsageResponse'
          description: ''
      summary: Query data usage
      tags:
      - Data Usage Query Service
      x-coralogixPermissions:
      - data-usage:Read
components:
  schemas:
    UsageLabelFilter:
      required:
      - key
      - operator
      - values
      type: object
      properties:
        key:
          maxLength: 256
          minLength: 1
          pattern: ^[A-Za-z][A-Za-z0-9_]*$
          type: string
          description: Label key to filter on. Supported keys are listed by the capabilities endpoint.
          examples:
          - pillar
        operator:
          allOf:
          - $ref: '#/components/schemas/UsageLabelFilter.FilterOperator'
          description: How `values` is matched against the label.
        values:
          maxItems: 1024
          minItems: 1
          type: array
          items:
            maxLength: 1024
            minLength: 0
            pattern: ^[\s\S]*$
            type: string
            description: Values to match against `key`. Required and must be non-empty when an `operator` is set.
          description: Values to match against `key`. Required and must be non-empty when an `operator` is set.
          examples:
          - - logs
      description: Predicate applied to a single label before aggregation. A complete predicate requires `key`, `operator`, and a non-empty `values` list.
    UsageLimit:
      type: object
      properties:
        perBucket:
          maximum: 100000
          minimum: 1
          type: integer
          description: Maximum number of usage entries returned per bucket. The server may apply a lower hard limit.
          format: int64
      description: Per-bucket result-size cap requested by the client.
    UsageCalendarDateRange:
      required:
      - start
      - end
      type: object
      properties:
        end:
          allOf:
          - $ref: '#/components/schemas/Date'
          description: Exclusive end of the range, as a full UTC calendar date later than `start`.
        start:
          allOf:
          - $ref: '#/components/schemas/Date'
          description: Inclusive start of the range, as a full UTC calendar date.
      description: Half-open UTC calendar date interval `[start, end)`. Both bounds are required full calendar dates.
    UsageMeasurementUnit:
      title: Measurement unit
      enum:
      - MEASUREMENT_UNIT_UNSPECIFIED
      - MEASUREMENT_UNIT_BYTES
      - MEASUREMENT_UNIT_TOKENS
      - MEASUREMENT_UNIT_EVENTS
      type: string
      description: Raw unit of a measured amount.
    Bucket:
      type: object
      properties:
        entries:
          maxItems: 100000
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/UsageEntry'
          description: Usage entries inside this bucket, one per unique combination of `groupBy` values.
        range:
          allOf:
          - $ref: '#/components/schemas/UsageTimestampRange'
          description: Half-open timestamp range for this bucket.
      description: A single time bucket of grouped usage entries.
    UsageGroupBy:
      type: object
      properties:
        keys:
          maxItems: 16
          minItems: 0
          type: array
          items:
            maxLength: 256
            minLength: 1
            pattern: ^[A-Za-z][A-Za-z0-9_]*$
            type: string
            description: Label key to group by. Supported keys are listed by the capabilities endpoint.
          description: Label key to group by. Supported keys are listed by the capabilities endpoint.
          examples:
          - - feature_id
      description: Set of canonical label keys to group results by.
    Date:
      required:
      - year
      - month
      - day
      type: object
      properties:
        day:
          maximum: 31
          minimum: 1
          type: integer
          description: Day of the month. Must be from 1 to 31 and valid for the year and month.
          format: int32
        month:
          maximum: 12
          minimum: 1
          type: integer
          description: Month of the year. Must be from 1 to 12.
          format: int32
        year:
          maximum: 9999
          minimum: 1
          type: integer
          description: Year of the date. Must be from 1 to 9999.
          format: int32
      description: A full calendar date (year, month, day). All three components are required.
    UsageHourlyQuery:
      type: object
      oneOf:
      - required:
        - timeRange
        type: object
      - required:
        - relativeRange
        type: object
      - type: object
        not:
          anyOf:
          - required:
            - timeRange
            type: object
          - required:
            - relativeRange
            type: object
      properties:
        relativeRange:
          $ref: '#/components/schemas/UsageHourlyRelativeRange'
        timeRange:
          $ref: '#/components/schemas/UsageTimestampRange'
      description: 'Hour-oriented query. Always returns 1-hour buckets. Max window: 14 days.'
    GetDataUsageCapabilitiesResponse:
      type: object
      properties:
        maxFilterValues:
          maximum: 1024
          minimum: 0
          type: integer
          description: Maximum number of values accepted by one label filter.
          format: int64
        maxFilters:
          maximum: 16
          minimum: 0
          type: integer
          description: Maximum number of label filters accepted in one query.
          format: int64
        maxGroupByLabels:
          maximum: 16
          minimum: 0
          type: integer
          description: Maximum number of label keys accepted in a `groupBy` request.
          format: int64
        maxUsageEntriesPerMessage:
          maximum: 1000000
          minimum: 0
          type: integer
          description: Maximum number of usage entries the server may include in a single response. `0` means no fixed entry limit is advertised.
          format: int64
        supportedLabels:
          maxItems: 256
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/UsageCapabilityLabel'
          description: Supported labels for the public API surface, with descriptions, cardinality hints, and any stable known values.
        supportedMeasurements:
          maxItems: 32
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/UsageCapabilityMeasurement'
          description: Supported measurement kinds and raw units returned by `UsageEntry`.
      description: Capabilities of the public data-usage query surface in v1.
    UsageMeasurementKind:
      title: Measurement kind
      enum:
      - MEASUREMENT_KIND_UNSPECIFIED
      - MEASUREMENT_KIND_PROCESSED_DATA_SIZE
      - MEASUREMENT_KIND_EVALUATIONS
      - MEASUREMENT_KIND_PROCESSED_EVENTS
      - MEASUREMENT_KIND_OLLY
      type: string
      description: Type of usage this entry reports.
    UsageCapabilityLabel.LabelValue:
      type: object
      properties:
        description:
          maxLength: 4096
          minLength: 0
          pattern: ^[\s\S]*$
          type: string
          description: Short user-facing description of this value.
        value:
          maxLength: 1024
          minLength: 0
          pattern: ^[\s\S]*$
          type: string
          description: The label value.
          examples:
          - logs_ingestion
      description: A known value for a label, with a short description.
    UsageCapabilityLabel:
      type: object
      properties:
        highCardinality:
          type: boolean
          description: Whether this label is considered high cardinality and therefore more likely to produce large result sets.
        key:
          maxLength: 256
          minLength: 1
          pattern: ^[A-Za-z][A-Za-z0-9_]*$
          type: string
          description: Canonical label key string.
          examples:
          - feature_id
        keyDescription:
          maxLength: 4096
          minLength: 0
          pattern: ^[\s\S]*$
          type: string
          description: Short user-facing description of the label.
        knownValues:
          maxItems: 4096
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/UsageCapabilityLabel.LabelValue'
          description: Stable known values for the label when available. May be incomplete for dynamic or evolving labels.
      description: A label supported by the public data-usage query surface.
    UsageCapabilityMeasurement:
      type: object
      properties:
        description:
          maxLength: 4096
          minLength: 0
          pattern: ^[\s\S]*$
          type: string
          description: Short user-facing description of this measurement kind.
        kind:
          allOf:
          - $ref: '#/components/schemas/UsageMeasurementKind'
          description: Server-defined measurement kind.
        unit:
          allOf:
          - $ref: '#/components/schemas/UsageMeasurementUnit'
          description: Raw unit returned for this measurement kind.
      description: A measurement kind supported by the public data-usage query surface, with its raw unit.
    DataUsageResponse:
      type: object
      properties:
        buckets:
          maxItems: 1827
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/Bucket'
          description: Bucket-first usage results. Daily queries yield one bucket per UTC calendar day; hourly queries yield one bucket per UTC hour.
        queryRange:
          allOf:
          - $ref: '#/components/schemas/UsageTimestampRange'
          description: Resolved half-open timestamp range of the query after applying absolute or relative interval semantics.
      description: Bucket-first usage results for the resolved query interval.
    UsageLabel:
      type: object
      properties:
        key:
          maxLength: 256
          minLength: 1
          pattern: ^[A-Za-z][A-Za-z0-9_]*$
          type: string
          description: Canonical response label key string.
          examples:
          - feature_id
        value:
          maxLength: 1024
          minLength: 0
          pattern: ^[\s\S]*$
          type: string
          description: Value of the label for this row.
          examples:
          - logs_ingestion
      description: A single label key/value pair in the grouped result.
    UsageHourlyRelativeRange:
      title: Hourly relative range
      enum:
      - HOURLY_RELATIVE_RANGE_UNSPECIFIED
      - HOURLY_RELATIVE_RANGE_LAST_12_HOURS
      - HOURLY_RELATIVE_RANGE_LAST_24_HOURS
      - HOURLY_RELATIVE_RANGE_LAST_48_HOURS
      - HOURLY_RELATIVE_RANGE_LAST_7_DAYS
      - HOURLY_RELATIVE_RANGE_LAST_14_DAYS
      type: string
      description: Relative hour-oriented presets resolved by the server at request time.
    UsageTimestampRange:
      required:
      - start
      - end
      type: object
      properties:
        end:
          description: Exclusive end of the timestamp range, as a UTC timestamp string later than `start`.
          examples:
          - '2026-06-08T00:00:00.000Z'
          format: date-time
          maxLength: 32
          minLength: 0
          type: string
          x-coralogix-presence: true
        start:
          description: Inclusive start of the timestamp range, as a UTC timestamp string.
          examples:
          - '2026-06-01T00:00:00.000Z'
          format: date-time
          maxLength: 32
          minLength: 0
          type: string
          x-coralogix-presence: true
      description: Half-open timestamp interval `[start, end)`. Both bounds are required.
    UsageEntry:
      type: object
      properties:
        labels:
          maxItems: 16
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/UsageLabel'
          description: Label values matching the request's `groupBy` keys. Empty when the request does not group by labels.
        measurements:
          maxItems: 8
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/UsageMeasurement'
          description: Raw usage measurements for this label combination.
      description: One row of usage for a unique combination of grouped label values, with its raw measurements.
    UsageDailyQuery:
      type: object
      oneOf:
      - required:
        - dateRange
        type: object
      - required:
        - relativeRange
        type: object
      - type: object
        not:
          anyOf:
          - required:
            - dateRange
            type: object
          - required:
            - relativeRange
            type: object
      properties:
        dateRange:
          $ref: '#/components/schemas/UsageCalendarDateRange'
        relativeRange:
          $ref: '#/components/schemas/UsageDailyRelativeRange'
      description: Day-oriented query. Always returns 1-day UTC buckets.
    UsageMeasurement:
      type: object
      properties:
        cxQuotaUnits:
          type: object
          properties:
            value:
              maxLength: 128
              minLength: 1
              pattern: ^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$
              type: string
              description: Decimal value encoded as a string, using optional sign, fraction, and exponent notation.
          description: Billable units charged for this measurement. The decimal magnitude is carried as a string in the `value` field of this object.
          examples:
          - value: '1.5'
        kind:
          allOf:
          - $ref: '#/components/schemas/UsageMeasurementKind'
          description: Server-defined measurement kind for this row.
        measuredUnit:
          allOf:
          - $ref: '#/components/schemas/UsageMeasurementUnit'
          description: Unit of the raw measured amount.
        measuredValue:
          maxLength: 20
          minLength: 1
          pattern: ^[0-9]+$
          type: string
          description: Raw measured amount for this usage row, in the unit indicated by `measuredUnit`.
      description: Raw measurement of a single kind for the parent usage row.
    UsageDailyRelativeRange:
      title: Daily relative range
      enum:
      - DAILY_RELATIVE_RANGE_UNSPECIFIED
      - DAILY_RELATIVE_RANGE_CURRENT_MONTH
      - DAILY_RELATIVE_RANGE_PREVIOUS_MONTH
      - DAILY_RELATIVE_RANGE_CURRENT_YEAR
      - DAILY_RELATIVE_RANGE_LAST_7_DAYS
      - DAILY_RELATIVE_RANGE_LAST_14_DAYS
      - DAILY_RELATIVE_RANGE_LAST_30_DAYS
      - DAILY_RELATIVE_RANGE_LAST_90_DAYS
      - DAILY_RELATIVE_RANGE_LAST_180_DAYS
      - DAILY_RELATIVE_RANGE_LAST_365_DAYS
      type: string
      description: Relative day-oriented presets resolved by the server at request time.
    UsageLabelFilter.FilterOperator:
      title: Label filter operator
      enum:
      - FILTER_OPERATOR_UNSPECIFIED
      - FILTER_OPERATOR_IN
      - FILTER_OPERATOR_NOT_IN
      type: string
      description: 'How `values` are matched against the label: inclusively (one of) or exclusively (none of).'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication
externalDocs:
  description: Coralogix API reference
  url: https://coralogix.com/docs/api-reference/v5/
x-provenance:
  method: harvested
  publisher: Coralogix
  source: https://coralogix.com/docs/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)