create_saved_report
const url = 'https://app.everruns.com/api/v1/reports/saved';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"dashboard":{"chart_type":"example","position":1,"section":"example","title":"example"},"description":"Rolling 30-day count of agents with at least one session per day, grouped by org.","name":"Weekly active agents — last 30 days","query":{"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);}curl --request POST \ --url https://app.everruns.com/api/v1/reports/saved \ --header 'Content-Type: application/json' \ --data '{ "dashboard": { "chart_type": "example", "position": 1, "section": "example", "title": "example" }, "description": "Rolling 30-day count of agents with at least one session per day, grouped by org.", "name": "Weekly active agents — last 30 days", "query": { "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" } } }'Create a new saved report.
Request Body required
Section titled “Request Body required ”Request body for the create_saved_report operation.
object
Optional dashboard placement metadata. Omit to create a library-only report that isn’t pinned to any dashboard layout.
object
Rendering hint for the UI (e.g. "line", "bar", "table",
"big_number"). Free-form string — the server doesn’t enforce a
closed set so new chart types can roll out client-side first.
Sort key within section. Lower values render first. None means
“place at the end”.
Dashboard section/group this report belongs to (free-form bucket name
like "Operations" or "Finance"). Used to cluster related reports
in the UI.
Human-readable title. Safe to render in user-facing messages.
Human-readable description. Safe to render in user-facing messages.
Example
Rolling 30-day count of agents with at least one session per day, grouped by org.Human-readable name. Safe to render in user-facing messages.
Example
Weekly active agents — last 30 daysThe query this report executes when run or exported. See ReportQuery
for the full field breakdown.
object
Dataset name to query (see GET /v1/reports/catalog for the list of available datasets).
Example
sessionsColumns to group by. Empty list returns one aggregate row.
Example
[ "status"]Predicate filters applied before aggregation.
One predicate filter applied to the dataset before aggregation. Combined with other filters via logical AND.
object
Field to filter on. Must be a filter field exposed by the dataset (see filter_fields in the catalog).
Example
statusComparison operator. Determines the expected shape of value
(scalar for eq/neq/gt/gte/lt/lte, array for in).
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"].
Maximum number of rows to return (defaults to 100).
Example
100Aggregations to compute (count, sum, avg, etc.). Empty list returns row counts only.
Example
[ "session_count", "avg_duration_ms"]Sort spec applied after aggregation. Empty list yields unspecified order.
One sort clause applied to the aggregated result. Either dimension
OR measure is set (mutually exclusive), never both.
object
Dimension name to sort by. Mutually exclusive with measure.
Example
org_idSort direction (asc or desc). Defaults to asc.
Measure name to sort by. Mutually exclusive with dimension.
Example
session_countTime window for the query. The dataset selects which timestamp column the range applies to.
object
Start of the window (RFC 3339, inclusive).
Example
2026-04-24T00:00:00ZEnd of the window (RFC 3339, exclusive).
Example
2026-05-24T00:00:00ZResponses
Section titled “ Responses ”Saved report
A user-saved report definition — a named, persistable wrapper around a
ReportQuery with optional dashboard placement metadata.
object
Timestamp when this resource was created (RFC 3339).
Optional dashboard placement metadata. None means the report is
“library-only” and not pinned to a dashboard layout.
object
Rendering hint for the UI (e.g. "line", "bar", "table",
"big_number"). Free-form string — the server doesn’t enforce a
closed set so new chart types can roll out client-side first.
Sort key within section. Lower values render first. None means
“place at the end”.
Dashboard section/group this report belongs to (free-form bucket name
like "Operations" or "Finance"). Used to cluster related reports
in the UI.
Human-readable title. Safe to render in user-facing messages.
Human-readable description. Safe to render in user-facing messages.
UUID of the saved report.
Human-readable name. Safe to render in user-facing messages.
The query this report executes when run or exported. Same shape as the
body of POST /v1/reports/query — see ReportQuery for the field
breakdown.
object
Dataset name to query (see GET /v1/reports/catalog for the list of available datasets).
Columns to group by. Empty list returns one aggregate row.
Predicate filters applied before aggregation.
One predicate filter applied to the dataset before aggregation. Combined with other filters via logical AND.
object
Field to filter on. Must be a filter field exposed by the dataset (see filter_fields in the catalog).
Comparison operator. Determines the expected shape of value
(scalar for eq/neq/gt/gte/lt/lte, array for in).
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"].
Maximum number of rows to return (defaults to 100).
Aggregations to compute (count, sum, avg, etc.). Empty list returns row counts only.
Sort spec applied after aggregation. Empty list yields unspecified order.
One sort clause applied to the aggregated result. Either dimension
OR measure is set (mutually exclusive), never both.
object
Dimension name to sort by. Mutually exclusive with measure.
Sort direction (asc or desc). Defaults to asc.
Measure name to sort by. Mutually exclusive with dimension.
Time window for the query. The dataset selects which timestamp column the range applies to.
object
Start of the window (RFC 3339, inclusive).
End of the window (RFC 3339, exclusive).
Timestamp when this resource was last updated (RFC 3339).
Example
{ "query": { "dataset": "sessions", "dimensions": [ "status" ], "filters": [ { "field": "status", "op": "eq" } ], "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" } }}Invalid saved report
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
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon 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
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
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.
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.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
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.
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.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
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"}Forbidden
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
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon 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
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
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.
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.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
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.
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.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
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"}