Skip to content
deedglassdocs

Get the overview

GET
/v1/overview
curl --request GET \
  --url 'http://127.0.0.1:8080/v1/overview?window=24h' \
  --header 'Authorization: Bearer <token>' \
  --header 'Deedglass-Version: 2026-10-01'

The Overview screen’s numbers for your org (docs/OVERVIEW_METRICS.md has every definition). window is 24h (24 hourly buckets, the default) or 7d (28 six-hour buckets). to is the first bucket boundary at or after now, in UTC, so the current partial bucket is the last one; from is to minus the window; an action counts when from <= created_at < to. previous is the window before. Blocked means the decision was deny (policy, budget and Stop). not_witnessed is the window’s actions with no verdict. Approvals count every pending approval, whatever the window. agents is the 8 most recently active agents with today’s usage in the org’s time zone. attention holds at most 8 items in priority order (chain_broken, org_stopped, slot_invalidated, slot_lagging, mismatch, approval_expiring, budget_near): kinds and data, never sentences, except a mismatch’s witness summary. Answers are cached for 10 s per org and window. Any other parameter, or another window, is 400 validation_failed. A Console session (viewer and up) or an org admin key; agent keys get 403 insufficient_scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Deedglass-Version
string
/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/

The API version (YYYY-MM-DD). Leave it out to use your org’s pinned version (public routes use the latest). An unknown version is 400 api_version_invalid.

Query Parameters

Section titled “Query Parameters”
window
string
default: 24h
Allowed values: 24h 7d

24h (default) or 7d, sent once.

Responses

Section titled “Responses”

200

Section titled “200”

The overview.

Media typeapplication/json

GET /v1/overview (S25). docs/OVERVIEW_METRICS.md defines every number.

object
object
required
string
Allowed value: overview
window
required
string
Allowed values: 24h 7d
from
required

Inclusive.

string format: date-time
to
required

Exclusive; the first bucket boundary at or after now (UTC).

string format: date-time
timezone
required

The org’s time zone (IANA), the day usage.calls_today counts.

string
generated_at
required

When this answer was read (answers are cached for 10 s).

string format: date-time
actions
required
object
total
required
integer
previous
required

The same count over the window before.

integer
series
required

24 hourly or 28 six-hour buckets

Array<integer>
blocked
required
object
total
required
integer
previous
required

The same count over the window before.

integer
series
required

24 hourly or 28 six-hour buckets

Array<integer>
approvals
required
object
pending
required

Every pending approval

integer
expiring_soon
required

Pending approvals that expire within 15 minutes.

integer
next_expires_at
required
string | null format: date-time
verification
required
object
verified
required
integer
mismatch
required
integer
unverifiable
required
integer
not_witnessed
required

The window’s actions with no verdict: denied, failed before running, pending or in flight.

integer
by_level
required

Witnessed actions by level; the three sum to verified + mismatch + unverifiable.

object
L0
required
integer
L1
required
integer
L2
required
integer
series
required
object
verified
required
Array<integer>
mismatch
required
Array<integer>
unverifiable
required
Array<integer>
agents
required
object
object
required
string
Allowed value: list
has_more
required
boolean
data
required
Array<object>
<= 8 items
object
id
required
string
/^agt_[0-7][0-9a-hjkmnp-tv-z]{25}$/
name
required
string
status
required
string
Allowed values: active suspended stopped
last_action_at
required
string | null format: date-time
usage
required
object
calls_today
required
integer
spend_today
required
object
amount
required
integer
currency
required
string
/^[a-z]{3}$/
budgets
required

An agent’s limits; a limit left out means none. Money is in minor units (cents for usd, paise for inr). Deedglass stores and checks them now; the Gate enforces them when it ships. The full Budgets schema is in openapi.yaml.

object
attention
required
Array<object>
<= 8 items

One thing on the Overview that needs a person. The server sends a kind and its data; the Console words it. ref is the id to open (an action, approval, agent, connector or deed), or null. Data per kind: chain_broken {seq, deed, code, checked, checked_at}; org_stopped {since, by, reason}; slot_invalidated {connector, connector_id, status, status_reason}; slot_lagging {connector, connector_id, lag_bytes, threshold_bytes}; mismatch {tool, agent, agent_id, summary (the witness summary, verbatim), level}; approval_expiring {tool, agent, agent_id, expires_at, action}; budget_near {agent, agent_id, budget (calls_per_minute, calls_per_day or spend_per_day), used, limit, and currency for spend}. The full AttentionItem schema is in openapi.yaml.

object
Example
{
  "object": "overview",
  "window": "24h",
  "from": "2026-10-08T14:00:00.000Z",
  "to": "2026-10-09T14:00:00.000Z",
  "timezone": "Asia/Kolkata",
  "generated_at": "2026-10-09T13:59:58.000Z",
  "actions": {
    "total": 1204,
    "previous": 1115,
    "series": [
      31,
      28,
      44,
      52,
      61,
      49,
      55,
      58,
      60,
      47,
      50,
      49,
      52,
      54,
      51,
      48,
      46,
      53,
      55,
      57,
      50,
      44,
      41,
      38
    ]
  },
  "blocked": {
    "total": 37,
    "previous": 41,
    "series": [
      1,
      0,
      2,
      3,
      2,
      1,
      2,
      1,
      2,
      2,
      1,
      2,
      2,
      1,
      2,
      1,
      2,
      2,
      1,
      2,
      1,
      2,
      1,
      1
    ]
  },
  "approvals": {
    "pending": 2,
    "expiring_soon": 1,
    "next_expires_at": "2026-10-09T14:06:00.000Z"
  },
  "verification": {
    "verified": 1021,
    "mismatch": 3,
    "unverifiable": 58,
    "not_witnessed": 122,
    "by_level": {
      "L0": 400,
      "L1": 262,
      "L2": 420
    },
    "series": {
      "verified": [
        27,
        24,
        37,
        44,
        52,
        41,
        47,
        49,
        51,
        40,
        43,
        41,
        44,
        46,
        43,
        41,
        39,
        45,
        47,
        48,
        42,
        37,
        35,
        39
      ],
      "mismatch": [
        0,
        0,
        0,
        1,
        0,
        0,
        0,
        0,
        0,
        0,
        1,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        1,
        0,
        0,
        0
      ],
      "unverifiable": [
        2,
        2,
        3,
        3,
        3,
        3,
        3,
        2,
        3,
        2,
        2,
        2,
        2,
        3,
        2,
        2,
        2,
        2,
        3,
        3,
        2,
        2,
        2,
        2
      ]
    }
  },
  "agents": {
    "object": "list",
    "has_more": true,
    "data": [
      {
        "id": "agt_01k633rrmh3bcz2p39gg4vp46q",
        "name": "support-bot",
        "status": "active",
        "last_action_at": "2026-10-09T13:59:41.000Z",
        "usage": {
          "calls_today": 212,
          "spend_today": {
            "amount": 1200,
            "currency": "usd"
          }
        },
        "budgets": {
          "calls_per_day": 5000
        }
      }
    ]
  },
  "attention": [
    {
      "object": "attention_item",
      "kind": "mismatch",
      "severity": "high",
      "at": "2026-10-09T13:41:09.000Z",
      "ref": "act_01k6f0k9hx2q3c1m6b8v5r7w2d",
      "data": {
        "tool": "postgres.execute",
        "agent": "support-bot",
        "agent_id": "agt_01k633rrmh3bcz2p39gg4vp46q",
        "summary": "Postgres changed 301 rows in public.orders. The agent reported 1.",
        "level": "L2"
      }
    }
  ]
}

Headers

Section titled “Headers”
Deedglass-Request-Id
string
/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/

This request’s id. Quote it to support; it matches error.request_id.

Deedglass-Version
string

The API version this response follows.

default

Section titled “default”

An error. Every error has this envelope; doc_url explains the code.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error policy_error rate_limit_error api_error
code
required
string
Allowed values: invalid_api_key api_key_revoked api_key_expired agent_suspended agent_stopped org_stopped insufficient_scope policy_denied approval_required approval_expired budget_exceeded intent_required intent_invalid intent_replay tool_unknown connector_unavailable upstream_error timeout rate_limited idempotency_conflict validation_failed not_found conflict internal_error authentication_required method_not_allowed request_too_large unsupported_media_type invalid_json api_version_invalid idempotency_key_invalid idempotency_key_in_use service_unavailable session_expired csrf_failed insufficient_role login_link_invalid login_code_invalid last_owner policy_unavailable policy_invalid credentials_missing destination_blocked vault_unavailable upstream_auth_failed upstream_not_found upstream_rate_limited response_too_large statement_refused row_limit_exceeded database_role_unsafe database_not_ready witness_not_configured approval_decided already_countersigned approver_not_eligible self_approval approval_needs_person context_changed approval_unsatisfiable approval_link_invalid approval_link_review_only approver_unmapped stripe_live_key_refused stripe_livemode_detected upstream_approval_pending schedule_needs_approval action_executing from_denied undo_unavailable undo_plan_stale already_undone undo_conflict replay_too_large replay_window_invalid suggestion_stale shadow_slot_taken suggestion_decided observe_not_enabled pro_required
message
required

One or more calm sentences with the next step.

string
param
required

The request field, query parameter or header the error is about.

string | null
request_id
required
string
/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/
doc_url
required
string format: uri
diagnostics

On policy_invalid only. Each problem with its line, code and hint.

Array<object>

One finding about a policy file, with its position and the next step. Codes are stable and listed in docs/POLICY_ERRORS.md. In the policy_invalid error envelope each diagnostic also carries object: policy_diagnostic. The full PolicyDiagnostic schema is in openapi.yaml.

object
action

One agent action. Its sections mirror the deed’s. status is the one field an agent needs; state is the exact lifecycle state (docs/GATE.md). The Gate’s own responses (POST /v1/actions and its result report) add execution.result and witness.reasons; lists leave both out. The full Action schema is in openapi.yaml.

object
checks

On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).

Array<object>

One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.

object
Example
{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "There's no endpoint at GET /v1/helth. Did you mean /v1/health?",
    "param": null,
    "request_id": "req_01j9zr3m5k8q2w7x4t6v0b1c9d",
    "doc_url": "https://docs.deedglass.com/errors/not_found"
  }
}

Headers

Section titled “Headers”
Deedglass-Request-Id
string
/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/

This request’s id. Quote it to support; it matches error.request_id.

Deedglass-Version
string

The API version this response follows.