--- title: "Query raw trace events from engineering data sources" method: POST path: "/api/v1/eng-intel/trace" tags: ["Eng Intel: 3-Trace"] --- # Query raw trace events from engineering data sources `POST /api/v1/eng-intel/trace` ## Request - Base URL: `https://api.getcortexapp.com` - URL: `https://api.getcortexapp.com/api/v1/eng-intel/trace` - Auth: HTTP bearer Retrieve individual event records with flexible filtering, ordering, and pagination. Supports any engineering data source registered in the registry. ## Request body - TraceEventsRequest - `attributes` string[], required: List of attribute names to include in results. Empty returns all attributes. - `daysOfWeek` integer[]: 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). - `endDate` string, date-time, required: End of the time range to query - `filters` AttributeFilterObject[], required: Filters to apply to the query - `attribute` string, required - `operator` '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', required - `predicate` union, required: The value or values of the attribute to filter by. The specific predicate value should match the type of the attribute column and is either a scalar value or array of values depending on the operator. A single, scalar value for EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, LIKE, NOT_LIKE. LIKE and NOT_LIKE perform case insensitive matches on a string and use % wildcards to perform partial matching. An array of values for IN, NOT_IN, ANY, BETWEEN. BETWEEN takes an array of two arguments, the inclusive lower and upper bounds. The predicate is ignored for IS_NULL, IS_NOT_NULL, which accept null or empty object as arguments. - string - number - boolean - union[] - union - string - number - boolean - `limit` integer, required: Maximum number of results to return (max 500) - `nextPage` string: Pagination cursor from a previous response - `orderBy` OrderBy[], required: Ordering specification for results - `attribute` string, required - `direction` 'ASC' | 'DESC', required - `source` string, required: Data source to query (e.g., 'pull_requests', 'deployments') - `startDate` string, date-time, required: Start of the time range to query - `timeAttribute` string: Override the default time attribute for time-based filtering ## Response `200` Successfully executed trace query - TraceEventsResponse - `metadata` QueryMetadata, required: Query metadata describing the structure of returned columns - `columns` union[], required: List of column definitions describing each field in the result rows - union - AggregatedAttributeColumn: List of column definitions describing each field in the result rows - `alias` string, required - `category` string - `description` string - `name` string, required - `ordinal` integer, required: Zero-based column position in the result data rows - use this to map column metadata to actual row data values - `type` string, required - `aggregationFunction` 'SUM' | 'AVG' | 'COUNT' | 'RATIO' | 'MIN' | 'MAX' | 'P50' | 'P95' | 'RANKING' | 'COLLECT' | 'COLLECT_UNIQUE' | 'COUNT_UNIQUE' | 'LATEST', required: Type of aggregation function applied to the attribute - `attributeName` string, required: Name of the attribute field this column aggregates - `resultType` 'STRING' | 'BOOLEAN' | 'INTEGER' | 'DECIMAL' | 'DOUBLE' | 'DATE' | 'TREE' | 'DATETIME' | 'JSON' | 'ARRAY' | 'ENUM' | 'UNSUPPORTED', required: Type of the produced cell rather than of the underlying attribute - AttributeColumn: List of column definitions describing each field in the result rows - `alias` string, required - `category` string - `description` string - `name` string, required - `ordinal` integer, required: Zero-based column position in the result data rows - use this to map column metadata to actual row data values - `type` string, required - `attributeName` string, required: Name of the attribute field this column represents - EntityReferenceColumn: List of column definitions describing each field in the result rows - `alias` string, required - `category` string - `description` string - `name` string, required - `ordinal` integer, required: Zero-based column position in the result data rows - use this to map column metadata to actual row data values - `type` string, required - `attributeName` string, required: Name of the attribute that references the entity - `entityType` string, required: Type of entity being referenced (e.g., 'user', 'team', 'service') - `factScope` 'UNIQUE_PER_ROW' | 'SHARED_ACROSS_ROWS', required: 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. - MetricAggregateColumn: List of column definitions describing each field in the result rows - `alias` string, required - `category` string - `description` string - `name` string, required - `ordinal` integer, required: Zero-based column position in the result data rows - use this to map column metadata to actual row data values - `type` string, required - `aggregationFunction` 'SUM' | 'AVG' | 'COUNT' | 'RATIO' | 'MIN' | 'MAX' | 'P50' | 'P95' | 'RANKING' | 'COLLECT' | 'COLLECT_UNIQUE' | 'COUNT_UNIQUE' | 'LATEST', required: Type of aggregation function applied to the metric - `metricKey` string, required: Unique identifier of the metric being aggregated - MetricValueColumn: List of column definitions describing each field in the result rows - `alias` string, required - `category` string - `description` string - `name` string, required - `ordinal` integer, required: Zero-based column position in the result data rows - use this to map column metadata to actual row data values - `type` string, required - `metricKey` string, required: Unique identifier of the metric this column represents - TimeWindowColumn: List of column definitions describing each field in the result rows - `alias` string, required - `category` string - `description` string - `name` string, required - `ordinal` integer, required: Zero-based column position in the result data rows - use this to map column metadata to actual row data values - `type` string, required - `windowSize` object, required: Duration of the time window represented by this column - `nano` integer - `negative` boolean - `positive` boolean - `seconds` integer - `units` object[] - … - `zero` boolean - UrlColumn: List of column definitions describing each field in the result rows - `alias` string, required - `category` string - `description` string - `name` string, required - `ordinal` integer, required: Zero-based column position in the result data rows - use this to map column metadata to actual row data values - `type` string, required - `attributeName` string, required: Name of the attribute containing the URL - `nextPage` string: Cursor for the next page, or null when this is the last page. Pass it back as the request's nextPage. - `rows` array[], required: 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. - object[]: 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. ## Other responses - `400`: Invalid source, date range exceeds 6 months, limit exceeds 500, or validation errors - `403`: Forbidden - `429`: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay. ## Changes - **2026-11-03** `a7b058663c95`: 1 info - endpoint added [Operation history](https://skmtc.dev/cortex/apis/cortex-api/changes/api/v1/eng-intel/trace/post.md) --- [API](https://skmtc.dev/cortex/apis/cortex-api.md) - [All operations](https://skmtc.dev/cortex/apis/cortex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cortex/apis/cortex-api/revisions/a7b058663c95?raw)