> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/api/readme/eng-intel-metrics.md).

# Eng Intel: Metrics

Use these operations to query [Engineering Intelligence](/improve/eng-intelligence/eng-intelligence.md) data programmatically.

### Required permissions

Your API key must have the `View dev metrics` permission, and your workspace must have the Eng Intelligence product area enabled.

### Query workflow

Call `listMetricDefinitions` first. It returns the metric keys, data sources, and the `groupBy`, filter, and aggregation options each one supports — use the exact keys from that response when building a query. Then:

* **Metrics** — aggregated metric values, optionally grouped and compared against a prior period.
* **Trace** — the individual event records (pull requests, deployments, and so on) behind those aggregates.

Both query operations return results as `metadata` plus `rows`. Rows are positional, not keyed: the value at index `i` of each row corresponds to `metadata.columns[i]`. Queries are capped at a six-month date range, and trace queries at 500 rows per page.

## Operations

## List available engineering metric definitions

> Discover all available engineering metrics and their metadata. Use this before querying metrics to understand what data is available and how to query it effectively.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Eng Intel: 1-Registry"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"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"}},"schemas":{"MetricDefinitionsResponse":{"required":["metrics","view"],"type":"object","properties":{"metrics":{"type":"array","items":{"$ref":"#/components/schemas/MetricDefinition"}},"view":{"type":"string"}},"discriminator":{"propertyName":"view"}},"MetricDefinition":{"required":["displayName","key","readiness"],"type":"object","properties":{"description":{"type":"string"},"displayName":{"type":"string"},"key":{"type":"string"},"readiness":{"oneOf":[{"$ref":"#/components/schemas/NotReady"},{"$ref":"#/components/schemas/Ready"}]}}},"NotReady":{"type":"object","allOf":[{"$ref":"#/components/schemas/Readiness"},{"type":"object","properties":{"docsUrl":{"type":"string"},"hint":{"type":"string"},"providerDocsUrls":{"type":"array","items":{"$ref":"#/components/schemas/ProviderDocLink"}}}}]},"Readiness":{"required":["type"],"type":"object","properties":{"type":{"type":"string"}},"description":"Whether this metric is ready to use - includes hints if configuration is needed","discriminator":{"propertyName":"type"}},"ProviderDocLink":{"required":["provider","url"],"type":"object","properties":{"provider":{"type":"string"},"url":{"type":"string"}}},"Ready":{"type":"object","allOf":[{"$ref":"#/components/schemas/Readiness"}]},"BasicMetricDefinitionsResponse":{"required":["metrics"],"type":"object","allOf":[{"$ref":"#/components/schemas/MetricDefinitionsResponse"},{"type":"object","properties":{"metrics":{"type":"array","description":"List of available metric definitions with basic metadata","items":{"$ref":"#/components/schemas/BasicMetricDefinition"}}}},{"$ref":"#/components/schemas/MetricDefinitionsResponseObject"}]},"BasicMetricDefinition":{"required":["displayName","key","readiness"],"type":"object","properties":{"description":{"type":"string","description":"Description of what this metric measures"},"displayName":{"type":"string","description":"Human-readable name"},"key":{"type":"string","description":"Unique identifier for the metric (used in queries)"},"readiness":{"oneOf":[{"$ref":"#/components/schemas/NotReady"},{"$ref":"#/components/schemas/Ready"}]}},"description":"List of available metric definitions with basic metadata"},"MetricDefinitionsResponseObject":{"required":["metrics","view"],"type":"object","properties":{"metrics":{"type":"array","items":{"type":"object"}},"view":{"type":"string"}},"discriminator":{"propertyName":"view"}},"FullMetricDefinitionsResponse":{"required":["metrics","sources"],"type":"object","allOf":[{"$ref":"#/components/schemas/MetricDefinitionsResponse"},{"type":"object","properties":{"metrics":{"type":"array","description":"List of available metric definitions with full metadata","items":{"$ref":"#/components/schemas/FullMetricDefinition"}},"sources":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Source"},"description":"Map of source names to source metadata for query construction"}}},{"$ref":"#/components/schemas/MetricDefinitionsResponseObject"}]},"FullMetricDefinition":{"required":["displayName","key","readiness"],"type":"object","properties":{"description":{"type":"string","description":"Description of what this metric measures"},"displayName":{"type":"string","description":"Human-readable name"},"key":{"type":"string","description":"Unique identifier for the metric (used in queries)"},"orderByAttribute":{"type":"string","description":"The attribute used for ordering/sorting metric results"},"readiness":{"oneOf":[{"$ref":"#/components/schemas/NotReady"},{"$ref":"#/components/schemas/Ready"}]},"sourceRef":{"type":"string","description":"Reference to the data source in the sources map - indicates which integration provides this metric"},"supportedAggregations":{"type":"array","description":"Available aggregation functions for this metric (e.g., SUM, AVG, COUNT)","items":{"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"]}},"timeAttribute":{"$ref":"#/components/schemas/Attribute1"},"type":{"type":"string","description":"Type of metric: COUNT (discrete values), DURATION (time-based), RATIO/RATE (percentages), VALUE (continuous)","enum":["DURATION","COUNT","VALUE","RATE"]},"units":{"type":"string","description":"Units of measurement (e.g., 'seconds', 'count', 'percentage')"},"valence":{"type":"string","description":"Whether higher values are better (POSITIVE) or worse (NEGATIVE) for this metric","enum":["POSITIVE","NEGATIVE","NEUTRAL"]}},"description":"List of available metric definitions with full metadata"},"Attribute1":{"required":["name","type"],"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of what this field contains"},"name":{"type":"string","description":"Field name for use in queries"},"type":{"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"]}},"description":"Queryable fields available on this dimension"},"Source":{"required":["attributes","category","description","dimensions","filterOptions","groupByOptions","name"],"type":"object","properties":{"attributes":{"type":"array","description":"Queryable fields available directly on this source","items":{"$ref":"#/components/schemas/Attribute1"}},"category":{"type":"string","description":"Category this source belongs to (e.g. 'Version Control', 'CI-CD') -- the axis the product groups metrics by in its selector"},"description":{"type":"string","description":"Human-readable description of what data this source provides"},"dimensions":{"type":"array","description":"Related entities that can be joined for additional context","items":{"$ref":"#/components/schemas/Dimension"}},"filterOptions":{"type":"array","description":"Available filtering options for querying metrics","items":{"$ref":"#/components/schemas/FilterOption"}},"groupByOptions":{"type":"array","description":"Available grouping options for aggregating metrics","items":{"$ref":"#/components/schemas/GroupByOption"}},"name":{"type":"string","description":"Unique identifier for the source"}},"description":"Map of source names to source metadata for query construction"},"Dimension":{"required":["attributes","description","dimensionKey","displayName","name"],"type":"object","properties":{"attributes":{"type":"array","description":"Queryable fields available on this dimension","items":{"$ref":"#/components/schemas/Attribute1"}},"description":{"type":"string","description":"Description of the relationship this dimension represents"},"dimensionKey":{"type":"string","description":"Unprefixed base name identifying the dimension type across sources"},"displayName":{"type":"string","description":"Human-readable role of this dimension in the source context (e.g., Author, Reviewer)"},"name":{"type":"string","description":"Dimension identifier for use in queries"}},"description":"Related entities that can be joined for additional context"},"FilterOption":{"required":["displayName","filter","key"],"type":"object","properties":{"canonicalName":{"type":"string","description":"Canonical dimension name before source-specific overrides (e.g. 'User' instead of 'Author')"},"dimensionRole":{"type":"string","description":"Role of this dimension in the source context (e.g. 'Authors', 'Reviewers', 'Assignees')"},"dimensionRoleGroup":{"type":"string","description":"Optional grouping key for dimensions that share a canonical concept across roles (e.g. 'User' groups Author / Reviewer / Assignee)"},"displayName":{"type":"string","description":"Human-readable label for this filter"},"filter":{"type":"string","description":"Specific attribute to filter on"},"key":{"type":"string","description":"Field key to reference in queries"}},"description":"Available filtering options for querying metrics"},"GroupByOption":{"required":["displayName","key"],"type":"object","properties":{"canonicalName":{"type":"string","description":"Canonical dimension name before source-specific overrides (e.g. 'User' instead of 'Author')"},"dimensionRole":{"type":"string","description":"Role of this dimension in the source context (e.g. 'Authors', 'Reviewers', 'Assignees')"},"dimensionRoleGroup":{"type":"string","description":"Optional grouping key for dimensions that share a canonical concept across roles (e.g. 'User' groups Author / Reviewer / Assignee)"},"displayName":{"type":"string","description":"Human-readable label for this grouping"},"key":{"type":"string","description":"Field key to use in GROUP BY clause"}},"description":"Available grouping options for aggregating metrics"},"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"}}}},"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"}}}}}},"paths":{"/api/v1/eng-intel/registry/metrics/definitions":{"get":{"description":"Discover all available engineering metrics and their metadata. Use this before querying metrics to understand what data is available and how to query it effectively.","operationId":"listMetricDefinitions","parameters":[{"in":"query","name":"view","required":false,"schema":{"type":"string","default":"basic"}},{"in":"query","name":"key","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricDefinitionsResponse"}}},"description":"Successfully retrieved metric definitions"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BasicMetricDefinitionsResponse"},{"$ref":"#/components/schemas/FullMetricDefinitionsResponse"}]}}},"description":"Invalid query parameters or filters"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BasicMetricDefinitionsResponse"},{"$ref":"#/components/schemas/FullMetricDefinitionsResponse"}]}}},"description":"Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List available engineering metric definitions","tags":["Eng Intel: 1-Registry"]}}}}
```

## Execute point-in-time engineering metrics queries

> Query current metric values with optional period comparisons and flexible grouping. Supports batch queries for multiple metrics efficiently.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Eng Intel: 2-Metrics"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"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"}},"schemas":{"BatchPointInTimeRequest":{"required":["endTime","filters","groupBy","limit","metrics","orderBy","startTime"],"type":"object","properties":{"comparison":{"oneOf":[{"$ref":"#/components/schemas/FilterDefinedPeerComparison"},{"$ref":"#/components/schemas/TimeWindow"}]},"daysOfWeek":{"uniqueItems":true,"type":"array","description":"Optional day-of-week restriction (ISO: Monday=1..Sunday=7). When set, the query filters out rows whose time-attribute does not fall on one of these weekdays. Use {1,2,3,4,5} to exclude weekends. Empty set matches nothing.","items":{"type":"integer","description":"Optional day-of-week restriction (ISO: Monday=1..Sunday=7). When set, the query filters out rows whose time-attribute does not fall on one of these weekdays. Use {1,2,3,4,5} to exclude weekends. Empty set matches nothing.","format":"int32"}},"endTime":{"type":"string","description":"End time for the query period","format":"date-time"},"filters":{"type":"array","description":"Filters to apply to the data","items":{"$ref":"#/components/schemas/AttributeFilterObject"}},"groupBy":{"type":"array","description":"Fields to group results by","items":{"type":"string","description":"Fields to group results by"}},"limit":{"type":"integer","description":"Maximum number of results to return","format":"int32"},"metrics":{"type":"array","description":"List of metrics to query with their aggregation functions","items":{"$ref":"#/components/schemas/MetricAggregation"}},"nestedAggregations":{"type":"array","description":"Nested aggregations for advanced sub-queries","items":{"$ref":"#/components/schemas/NestedAggregation"}},"nextPage":{"type":"string","description":"Pagination token for next page of results"},"orderBy":{"type":"array","description":"Sort order for results","items":{"$ref":"#/components/schemas/OrderBy"}},"startTime":{"type":"string","description":"Start time for the query period","format":"date-time"},"timeAttribute":{"type":"string","description":"Deprecated: use timeAttributes instead. Single time attribute override as a fully-qualified path (e.g. 'pull_requests.date_closed')."},"timeAttributes":{"type":"array","description":"Time attributes to use for queries. Each entry is a fully-qualified attribute path (e.g. 'pull_requests.date_closed'). The source is inferred from the prefix. For single-source queries, provide one entry. For multi-source, provide one per source to override.","items":{"type":"string","description":"Time attributes to use for queries. Each entry is a fully-qualified attribute path (e.g. 'pull_requests.date_closed'). The source is inferred from the prefix. For single-source queries, provide one entry. For multi-source, provide one per source to override."}}},"description":"Point-in-time metrics query request for batch processing"},"FilterDefinedPeerComparison":{"required":["peerFilters"],"type":"object","allOf":[{"$ref":"#/components/schemas/PointInTimeComparison"},{"type":"object","properties":{"peerFilters":{"type":"array","items":{"$ref":"#/components/schemas/AttributeFilterObject"}}}}]},"PointInTimeComparison":{"required":["type"],"type":"object","properties":{"type":{"type":"string"}},"description":"Optional comparison to previous time period","discriminator":{"propertyName":"type"}},"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"},"TimeWindow":{"required":["alias","name","ordinal","windowSize"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"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"}},"MetricAggregation":{"required":["aggregation","metric"],"type":"object","properties":{"aggregation":{"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"]},"density":{"type":"string","enum":["REQUIRED","OPTIONAL"]},"endTime":{"type":"string","format":"date-time"},"filters":{"type":"array","items":{"$ref":"#/components/schemas/AttributeFilterObject"}},"metric":{"type":"string"},"startTime":{"type":"string","format":"date-time"}}},"NestedAggregation":{"required":["aggregations","groupBy"],"type":"object","properties":{"aggregations":{"type":"array","items":{"$ref":"#/components/schemas/MetricAggregation"}},"filters":{"type":"array","items":{"$ref":"#/components/schemas/AttributeFilterObject"}},"groupBy":{"type":"array","items":{"type":"string"}},"timeAttribute":{"type":"string"}},"description":"Nested aggregations for advanced sub-queries"},"OrderBy":{"required":["attribute","direction"],"type":"object","properties":{"attribute":{"type":"string"},"direction":{"type":"string","enum":["ASC","DESC"]}},"description":"Ordering specification for results"},"PointInTimeResponse":{"required":["metadata","rows"],"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/QueryMetadata"},"rows":{"type":"array","description":"Result rows, one array per grouping. 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.","items":{"type":"array","description":"Result rows, one array per grouping. 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.","items":{"type":"object","description":"Result rows, one array per grouping. 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."}}}}},"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/AggregatedAttribute"},{"$ref":"#/components/schemas/Attribute"},{"$ref":"#/components/schemas/EntityReference"},{"$ref":"#/components/schemas/MetricAggregate"},{"$ref":"#/components/schemas/MetricValue"},{"$ref":"#/components/schemas/TimeWindow"},{"$ref":"#/components/schemas/Url"}]}},"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"},"AggregatedAttribute":{"required":["aggregationFunction","alias","attributeName","name","ordinal","resultType"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"]}}}]},"Attribute":{"required":["alias","attributeName","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"EntityReference":{"required":["alias","attributeName","entityType","factScope","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"MetricAggregate":{"required":["aggregationFunction","alias","metricKey","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"MetricValue":{"required":["alias","metricKey","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"Url":{"required":["alias","attributeName","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"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"}}}},"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"}}}}}},"paths":{"/api/v1/eng-intel/metrics/point-in-time":{"post":{"description":"Query current metric values with optional period comparisons and flexible grouping. Supports batch queries for multiple metrics efficiently.","operationId":"queryPointInTimeMetrics","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPointInTimeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointInTimeResponse"}}},"description":"Successfully executed metrics query"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointInTimeResponse"}}},"description":"Invalid metric names, date range exceeds 6 months, validation errors, or unsupported orderBy attributes"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointInTimeResponse"}}},"description":"Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Execute point-in-time engineering metrics queries","tags":["Eng Intel: 2-Metrics"]}}}}
```

## 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.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Eng Intel: 3-Trace"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"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"}},"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"}}},"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"},"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.","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.","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."}}}}},"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/AggregatedAttribute"},{"$ref":"#/components/schemas/Attribute"},{"$ref":"#/components/schemas/EntityReference"},{"$ref":"#/components/schemas/MetricAggregate"},{"$ref":"#/components/schemas/MetricValue"},{"$ref":"#/components/schemas/TimeWindow"},{"$ref":"#/components/schemas/Url"}]}},"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"},"AggregatedAttribute":{"required":["aggregationFunction","alias","attributeName","name","ordinal","resultType"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"]}}}]},"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"}},"Attribute":{"required":["alias","attributeName","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"EntityReference":{"required":["alias","attributeName","entityType","factScope","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"MetricAggregate":{"required":["aggregationFunction","alias","metricKey","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"MetricValue":{"required":["alias","metricKey","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"TimeWindow":{"required":["alias","name","ordinal","windowSize"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"Url":{"required":["alias","attributeName","name","ordinal"],"type":"object","allOf":[{"$ref":"#/components/schemas/Column"},{"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"}}}]},"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"}}}},"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"}}}}}},"paths":{"/api/v1/eng-intel/trace":{"post":{"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"}},"summary":"Query raw trace events from engineering data sources","tags":["Eng Intel: 3-Trace"]}}}}
```