run_query

POST

/v1/reports/query

curl --request POST \
  --url https://app.everruns.com/api/v1/reports/query \
  --header 'Content-Type: application/json' \
  --data '{ "dataset": "sessions", "dimensions": [ "status" ], "filters": [ { "field": "status", "op": "eq", "value": "example" } ], "limit": 100, "measures": [ "session_count", "avg_duration_ms" ], "order_by": [ { "dimension": "org_id", "direction": "asc", "measure": "session_count" } ], "time_range": { "from": "2026-04-24T00:00:00Z", "to": "2026-05-24T00:00:00Z" } }'

• Production API

Run an ad-hoc reporting query against a registered dataset.

Request Body ^required

Media type application/json

Semantic query a caller submits to the reporting layer. The backend compiles this to its native query language, scopes it to the calling org, and returns a ReportResult.

object

dataset

required

Dataset name to query (see GET /v1/reports/catalog for the list of available datasets).

string

Example

sessions

dimensions

Columns to group by. Empty list returns one aggregate row.

Array<string>

Example

[
  "status"
]

filters

Predicate filters applied before aggregation.

Array<object>

One predicate filter applied to the dataset before aggregation. Combined with other filters via logical AND.

object

field

required

Field to filter on. Must be a filter field exposed by the dataset (see filter_fields in the catalog).

string

Example

status

op

required

Comparison operator. Determines the expected shape of value (scalar for eq/neq/gt/gte/lt/lte, array for in).

string

Allowed values: eq neq in gt gte lt lte

value

required

Comparison value. Type depends on op: a scalar for eq/neq/gt/gte/lt/lte, an array for in. Example for op = in: ["completed", "failed"].

limit

Maximum number of rows to return (defaults to 100).

integer format: int32

Example

100

measures

Aggregations to compute (count, sum, avg, etc.). Empty list returns row counts only.

Array<string>

Example

[
  "session_count",
  "avg_duration_ms"
]

order_by

Sort spec applied after aggregation. Empty list yields unspecified order.

Array<object>

One sort clause applied to the aggregated result. Either dimension OR measure is set (mutually exclusive), never both.

object

dimension

Dimension name to sort by. Mutually exclusive with measure.

string | null

Example

org_id

direction

Sort direction (asc or desc). Defaults to asc.

string

Allowed values: asc desc

measure

Measure name to sort by. Mutually exclusive with dimension.

string | null

Example

session_count

time_range

required

Time window for the query. The dataset selects which timestamp column the range applies to.

object

from

required

Start of the window (RFC 3339, inclusive).

string format: date-time

Example

2026-04-24T00:00:00Z

to

required

End of the window (RFC 3339, exclusive).

string format: date-time

Example

2026-05-24T00:00:00Z

Responses

200

Reporting query result

Media type application/json

Materialized result of a report query — column metadata, rows, and the freshness of the underlying data.

object

as_of

required

Timestamp the underlying data was materialized (RFC 3339). Useful as an “as of” footer when rendering — distinct from when the query ran.

string format: date-time

columns

required

Column metadata in the same order as the entries of each row in rows. Use the kind field to tell dimensions from measures.

Array<object>

One column header in a ReportResult. The ordered columns list declares the key set of each row in rows.

object

kind

required

Whether this column is a grouping dimension or an aggregate measure — the same distinction made on ReportQuery.

string

Allowed values: dimension measure

name

required

Column name as it appears in rows.

string

freshness_lag_ms

How stale the data is relative to the server’s wall clock at query time, in milliseconds. None when freshness can’t be determined (e.g. backends that don’t track projector lag).

integer | null format: int64

rows

required

Result rows. Each row is a JSON object keyed by column name; cell types match the underlying dataset (numbers for measures, strings or numbers for dimensions). Length is capped by ReportQuery.limit.

Array

Example

{
  "columns": [
    {
      "kind": "dimension",
      "name": "session_count"
    }
  ]
}

400

Invalid semantic query

Media type application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

• Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
• Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

403

Forbidden

Media type application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

• Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
• Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}