Refresh Metrics

Metrics storage and access

Use a registered metrics-capable database. Specify db_id when multiple database IDs are available; selecting table requires db_id. Configured authorization uses metrics:read for reads and metrics:write for refresh.

The effective user_id is fixed for scoped callers: JWT user isolation is opt-in, while non-admin service-account PAT callers self-scope. An unscoped caller can select a user. Current RemoteDb GET/refresh forwarding does not pass an explicit user filter; do not assume a local admin filter is forwarded to another AgentOS. Downstream credential-based scoping is separate.

Refresh results

A synchronous refresh returns an array of newly calculated rows, which can be empty when there is no work, or a response with status="already_running". It does not promise unconditional recomputation of all historical data.

With background=true, a new refresh returns 202. Poll Get Metrics Refresh Status, then read /metrics. Status and overlap protection are process-local, not a cluster-wide lock.

POST/metrics/refresh

Manually trigger recalculation of system metrics from raw data. This operation analyzes system activity logs and regenerates aggregated metrics. Useful for ensuring metrics are up-to-date or after system maintenance. By default the refresh runs synchronously and returns the refreshed metrics. Pass background=true to run the refresh in the background instead: the endpoint returns 202 Accepted immediately and GET /metrics can be polled for results. If a background refresh is already in progress for the target database, returns status 'already_running' without starting a new one.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

db_id?|

Database ID to use for metrics calculation

table?|

Table to use for metrics calculation

user_id?|

Return only this user's metrics. Ignored for non-admin callers

background?Background

Run the refresh in the background and return 202 immediately

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl --request POST 'https://example.com/metrics/refresh'
[  {    "id": "2025-08-12_daily",    "agent_runs_count": 2,    "agent_sessions_count": 2,    "team_runs_count": 0,    "team_sessions_count": 0,    "workflow_runs_count": 0,    "workflow_sessions_count": 0,    "users_count": 1,    "token_metrics": {      "input_tokens": 256,      "output_tokens": 441,      "total_tokens": 697    },    "model_metrics": [      {        "model_id": "gpt-5.5",        "model_provider": "OpenAI",        "count": 2      }    ],    "date": "2025-08-12T00:00:00Z",    "created_at": "2025-08-12T08:01:47Z",    "updated_at": "2025-08-12T08:01:47Z"  }]