> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Query raw trace events from engineering data sources

> Retrieve individual event records with flexible filtering, ordering, and pagination. Supports any engineering data source registered in the registry.



## OpenAPI

````yaml /openapi/cortex_swagger.json post /api/v1/eng-intel/trace
openapi: 3.0.1
info:
  description: >-
    The Cortex REST API provides programmatic access to the data in the catalog,
    Scorecards, and more.
  title: Cortex API
  version: v1
servers:
  - url: https://api.getcortexapp.com
    description: Cortex Cloud API host
security:
  - bearerAuth: []
tags:
  - name: API Keys
  - name: Audit Logs
  - name: Catalog Entities
  - name: Catalogs
  - name: Custom Data
  - name: Custom Data [Advanced]
  - name: Custom Events
  - name: Custom Metrics
  - name: Dependencies
  - name: Deploys
  - name: Discovery Audit
  - name: Docs
  - name: 'Eng Intel: 1-Registry'
  - name: 'Eng Intel: 2-Metrics'
  - name: 'Eng Intel: 3-Trace'
  - name: 'Eng Intel: User Labels'
  - name: Entity Relationship Types
  - name: Entity Relationships
  - name: Entity Types
  - name: GitOps Logs
  - name: Groups
  - name: IP Allowlist
  - name: Initiatives
  - name: My Workspace
  - name: Notification Logs
  - name: On-call
  - name: Packages
  - name: Plugins
  - name: Queries
  - name: SCIM
  - name: Scaffolder
  - name: Scorecards
  - name: Secrets
  - name: Team Roles
  - name: Teams
  - name: Teams Hierarchies
  - name: Teams [Advanced]
  - name: Teams [Departments] (legacy)
  - name: Users
  - name: Verifications
  - name: Workflows
  - name: '[Integrations] AWS'
  - name: '[Integrations] Anthropic'
  - name: '[Integrations] Apiiro'
  - name: '[Integrations] ArgoCD'
  - name: '[Integrations] Azure Active Directory'
  - name: '[Integrations] Azure Devops'
  - name: '[Integrations] Azure Resources'
  - name: '[Integrations] BambooHR'
  - name: '[Integrations] Bitbucket'
  - name: '[Integrations] Bugsnag'
  - name: '[Integrations] Buildkite'
  - name: '[Integrations] Checkmarx SAST'
  - name: '[Integrations] CircleCI'
  - name: '[Integrations] ClickUp'
  - name: '[Integrations] Codecov'
  - name: '[Integrations] Coralogix'
  - name: '[Integrations] Datadog'
  - name: '[Integrations] Dynatrace'
  - name: '[Integrations] Firehydrant'
  - name: '[Integrations] GitHub'
  - name: '[Integrations] GitLab'
  - name: '[Integrations] Harness'
  - name: '[Integrations] Incident.io'
  - name: '[Integrations] Instana'
  - name: '[Integrations] Jenkins'
  - name: '[Integrations] Jira'
  - name: '[Integrations] Kubernetes'
  - name: '[Integrations] LaunchDarkly'
  - name: '[Integrations] Lightstep'
  - name: '[Integrations] Mend SAST'
  - name: '[Integrations] Mend SCA'
  - name: '[Integrations] New Relic'
  - name: '[Integrations] Okta'
  - name: '[Integrations] Opsgenie'
  - name: '[Integrations] PagerDuty'
  - name: '[Integrations] Prometheus'
  - name: '[Integrations] Rollbar'
  - name: '[Integrations] Rootly'
  - name: '[Integrations] Semgrep'
  - name: '[Integrations] Sentry'
  - name: '[Integrations] ServiceNow'
  - name: '[Integrations] SignalFx'
  - name: '[Integrations] Snyk'
  - name: '[Integrations] SonarQube'
  - name: '[Integrations] SumoLogic'
  - name: '[Integrations] Veracode'
  - name: '[Integrations] VictorOps'
  - name: '[Integrations] Wiz'
  - name: '[Integrations] Workday'
  - name: '[Integrations] xMatters'
  - name: dev-login-controller
  - name: public-scim-schema-controller
paths:
  /api/v1/eng-intel/trace:
    post:
      tags:
        - Eng Intel Trace
      summary: Query raw trace events from engineering data sources
      description: >-
        Retrieve individual event records with flexible filtering, ordering, and
        pagination. Supports any engineering data source registered in the
        registry.
      operationId: queryTraceEvents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraceEventsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceEventsResponse'
          description: Successfully executed trace query
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceEventsResponse'
          description: >-
            Invalid source, date range exceeds 6 months, limit exceeds 500, or
            validation errors
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceEventsResponse'
          description: Forbidden
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    TraceEventsRequest:
      required:
        - attributes
        - endDate
        - filters
        - limit
        - orderBy
        - source
        - startDate
      type: object
      properties:
        attributes:
          type: array
          description: >-
            List of attribute names to include in results. Empty returns all
            attributes.
          items:
            type: string
            description: >-
              List of attribute names to include in results. Empty returns all
              attributes.
        daysOfWeek:
          uniqueItems: true
          type: array
          description: >-
            Optional day-of-week restriction (ISO: Monday=1..Sunday=7). When
            set, only events whose time attribute falls on one of these days are
            returned (e.g. [1,2,3,4,5] excludes weekends).
          items:
            type: integer
            description: >-
              Optional day-of-week restriction (ISO: Monday=1..Sunday=7). When
              set, only events whose time attribute falls on one of these days
              are returned (e.g. [1,2,3,4,5] excludes weekends).
            format: int32
        endDate:
          type: string
          description: End of the time range to query
          format: date-time
        filters:
          type: array
          description: Filters to apply to the query
          items:
            $ref: '#/components/schemas/AttributeFilterObject'
        limit:
          type: integer
          description: Maximum number of results to return (max 500)
          format: int32
        nextPage:
          type: string
          description: Pagination cursor from a previous response
        orderBy:
          type: array
          description: Ordering specification for results
          items:
            $ref: '#/components/schemas/OrderBy'
        source:
          type: string
          description: Data source to query (e.g., 'pull_requests', 'deployments')
        startDate:
          type: string
          description: Start of the time range to query
          format: date-time
        timeAttribute:
          type: string
          description: Override the default time attribute for time-based filtering
    TraceEventsResponse:
      required:
        - metadata
        - rows
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/QueryMetadata'
        rows:
          type: array
          description: >-
            Result rows, one array per event. Cells are positional: the value at
            index i corresponds to `metadata.columns[i]`, and its JSON type
            follows that column's type (string, number, boolean, or null). Rows
            are not keyed by column name.
          example:
            - - cortexapps/brain-backend
              - 42
              - '2026-01-15T09:30:00'
            - - cortexapps/brain-app
              - 7
              - null
          items:
            type: array
            description: >-
              Result rows, one array per event. Cells are positional: the value
              at index i corresponds to `metadata.columns[i]`, and its JSON type
              follows that column's type (string, number, boolean, or null).
              Rows are not keyed by column name.
            example:
              - - cortexapps/brain-backend
                - 42
                - '2026-01-15T09:30:00'
              - - cortexapps/brain-app
                - 7
                - null
            items:
              type: object
              description: >-
                Result rows, one array per event. Cells are positional: the
                value at index i corresponds to `metadata.columns[i]`, and its
                JSON type follows that column's type (string, number, boolean,
                or null). Rows are not keyed by column name.
              example:
                - - cortexapps/brain-backend
                  - 42
                  - '2026-01-15T09:30:00'
                - - cortexapps/brain-app
                  - 7
                  - null
    AttributeFilterObject:
      required:
        - attribute
        - operator
        - predicate
      type: object
      properties:
        attribute:
          type: string
        operator:
          type: string
          enum:
            - ANY
            - BETWEEN
            - CONTAINS
            - EQUAL
            - GREATER_THAN
            - GREATER_THAN_OR_EQUAL
            - IN
            - IS_NOT_NULL
            - IS_NULL
            - LESS_THAN
            - LESS_THAN_OR_EQUAL
            - LIKE
            - NOT_EQUAL
            - NOT_IN
            - NOT_LIKE
        predicate:
          type: object
      description: Filters to apply to the query
    OrderBy:
      required:
        - attribute
        - direction
      type: object
      properties:
        attribute:
          type: string
        direction:
          type: string
          enum:
            - ASC
            - DESC
      description: Ordering specification for results
    QueryMetadata:
      required:
        - columns
      type: object
      properties:
        columns:
          type: array
          description: List of column definitions describing each field in the result rows
          items:
            oneOf:
              - $ref: '#/components/schemas/AggregatedAttributeColumn'
              - $ref: '#/components/schemas/AttributeColumn'
              - $ref: '#/components/schemas/EntityReferenceColumn'
              - $ref: '#/components/schemas/MetricAggregateColumn'
              - $ref: '#/components/schemas/MetricValueColumn'
              - $ref: '#/components/schemas/TimeWindowColumn'
              - $ref: '#/components/schemas/UrlColumn'
        nextPage:
          type: string
          description: >-
            Cursor for the next page, or null when this is the last page. Pass
            it back as the request's nextPage.
      description: Query metadata describing the structure of returned columns
    TooManyRequestsProblemDetail:
      required:
        - type
        - title
        - status
      type: object
      properties:
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        retryAfter:
          minimum: 0
          type: integer
          description: The number of seconds until the rate limiting resets.
          format: int32
        status:
          maximum: 599
          minimum: 100
          type: integer
          format: int32
          enum:
            - 429
        title:
          type: string
        type:
          type: string
          format: uri-reference
    AggregatedAttributeColumn:
      type: object
      allOf:
        - $ref: '#/components/schemas/Column'
        - required:
            - aggregationFunction
            - attributeName
            - ordinal
            - resultType
          type: object
          properties:
            aggregationFunction:
              type: string
              description: Type of aggregation function applied to the attribute
              enum:
                - SUM
                - AVG
                - COUNT
                - RATIO
                - MIN
                - MAX
                - P50
                - P95
                - RANKING
                - COLLECT
                - COLLECT_UNIQUE
                - COUNT_UNIQUE
            attributeName:
              type: string
              description: Name of the attribute field this column aggregates
            ordinal:
              type: integer
              description: >-
                Zero-based column position in the result data rows - use this to
                map column metadata to actual row data values
              format: int32
            resultType:
              type: string
              description: >-
                Type of the produced cell rather than of the underlying
                attribute
              enum:
                - STRING
                - BOOLEAN
                - INTEGER
                - DECIMAL
                - DOUBLE
                - DATE
                - TREE
                - DATETIME
                - JSON
                - ARRAY
                - ENUM
                - UNSUPPORTED
    AttributeColumn:
      type: object
      allOf:
        - $ref: '#/components/schemas/Column'
        - required:
            - attributeName
            - ordinal
          type: object
          properties:
            attributeName:
              type: string
              description: Name of the attribute field this column represents
            ordinal:
              type: integer
              description: >-
                Zero-based column position in the result data rows - use this to
                map column metadata to actual row data values
              format: int32
    EntityReferenceColumn:
      type: object
      allOf:
        - $ref: '#/components/schemas/Column'
        - required:
            - attributeName
            - entityType
            - factScope
            - ordinal
          type: object
          properties:
            attributeName:
              type: string
              description: Name of the attribute that references the entity
            entityType:
              type: string
              description: >-
                Type of entity being referenced (e.g., 'user', 'team',
                'service')
            factScope:
              type: string
              description: >-
                Whether sibling rows under this grouping hold disjoint or
                overlapping facts. SHARED_ACROSS_ROWS means the grouping fans
                out (e.g. a repo maps to many entities), so the grouped values
                share underlying records and do not sum to the total;
                UNIQUE_PER_ROW means each row's values are its own and are
                additive.
              enum:
                - UNIQUE_PER_ROW
                - SHARED_ACROSS_ROWS
            ordinal:
              type: integer
              description: >-
                Zero-based column position in the result data rows - use this to
                map column metadata to actual row data values
              format: int32
    MetricAggregateColumn:
      type: object
      allOf:
        - $ref: '#/components/schemas/Column'
        - required:
            - aggregationFunction
            - metricKey
            - ordinal
          type: object
          properties:
            aggregationFunction:
              type: string
              description: Type of aggregation function applied to the attribute
              enum:
                - SUM
                - AVG
                - COUNT
                - RATIO
                - MIN
                - MAX
                - P50
                - P95
                - RANKING
                - COLLECT
                - COLLECT_UNIQUE
                - COUNT_UNIQUE
            metricKey:
              type: string
              description: Unique identifier of the metric being aggregated
            ordinal:
              type: integer
              description: >-
                Zero-based column position in the result data rows - use this to
                map column metadata to actual row data values
              format: int32
    MetricValueColumn:
      type: object
      allOf:
        - $ref: '#/components/schemas/Column'
        - required:
            - metricKey
            - ordinal
          type: object
          properties:
            metricKey:
              type: string
              description: Unique identifier of the metric this column represents
            ordinal:
              type: integer
              description: >-
                Zero-based column position in the result data rows - use this to
                map column metadata to actual row data values
              format: int32
    TimeWindowColumn:
      type: object
      allOf:
        - $ref: '#/components/schemas/Column'
        - required:
            - ordinal
            - windowSize
          type: object
          properties:
            ordinal:
              type: integer
              description: >-
                Zero-based column position in the result data rows - use this to
                map column metadata to actual row data values
              format: int32
            windowSize:
              type: object
              properties:
                nano:
                  type: integer
                  format: int32
                negative:
                  type: boolean
                positive:
                  type: boolean
                seconds:
                  type: integer
                  format: int64
                units:
                  type: array
                  items:
                    type: object
                    properties:
                      dateBased:
                        type: boolean
                      duration:
                        type: object
                        properties:
                          nano:
                            type: integer
                            format: int32
                          negative:
                            type: boolean
                          positive:
                            type: boolean
                          seconds:
                            type: integer
                            format: int64
                          zero:
                            type: boolean
                      durationEstimated:
                        type: boolean
                      timeBased:
                        type: boolean
                zero:
                  type: boolean
              description: Duration of the time window represented by this column
    UrlColumn:
      type: object
      allOf:
        - $ref: '#/components/schemas/Column'
        - required:
            - attributeName
            - ordinal
          type: object
          properties:
            attributeName:
              type: string
              description: Name of the attribute containing the URL
            ordinal:
              type: integer
              description: >-
                Zero-based column position in the result data rows - use this to
                map column metadata to actual row data values
              format: int32
    Column:
      required:
        - alias
        - name
        - ordinal
        - type
      type: object
      properties:
        alias:
          type: string
        category:
          type: string
        description:
          type: string
        name:
          type: string
        ordinal:
          type: integer
          format: int32
        type:
          type: string
      description: List of column definitions describing each field in the result rows
      discriminator:
        propertyName: type
  responses:
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsProblemDetail'
      description: >-
        The client has exceeded the rate limit by performing too many requests
        in a short period. Retry the request after a delay.
      headers:
        Retry-After:
          description: The number of seconds until the rate limiting resets.
          schema:
            minimum: 0
            type: integer
            format: int32
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: >-
        All requests to the Cortex API need to provide an `Authorization: Bearer
        <token>` header, where `<token>` is an API key created in the Settings
        page of your workspace.
      scheme: bearer
      type: http

````

## Related topics

- [Eng Intelligence: Trace](/api/rest/eng-intel-trace.md)
- [Eng Intelligence: Metrics](/api/rest/eng-intel-metrics.md)
- [Using the Cortex MCP](/get-started/cortex-ai-assistant/mcp/using-cortex-mcp.md)