# run_query

Source: <https://everruns.com/docs/api/operations/run_query/>

POST

/v1/reports/query

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/reports/query';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"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"}}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
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 APIapp.everruns.com/api/v1/reports/query

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

## Request Bodyrequired

Media typeapplication/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

```plaintext
sessions
```

**dimensions**

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

Array\<string>

##### Example

```json
[
  "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

```plaintext
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

```json
100
```

**measures**

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

Array\<string>

##### Example

```json
[
  "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

```plaintext
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

```plaintext
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

```plaintext
2026-04-24T00:00:00Z
```

**to**

required

End of the window (RFC 3339, exclusive).

string format: date-time

##### Example

```plaintext
2026-05-24T00:00:00Z
```

## Responses

### 200

Reporting query result

Media typeapplication/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

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

### 400

Invalid semantic query

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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` with the `application/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 `rel`s 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 `rel`s 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 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. 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

```json
{
  "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://everruns.com/docs/errors/session_not_found"
}
```

### 403

Forbidden

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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` with the `application/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 `rel`s 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 `rel`s 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 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. 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

```json
{
  "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://everruns.com/docs/errors/session_not_found"
}
```