---
title: "Read the workspace operating picture"
method: GET
path: "/account/summary"
tags: ["Account"]
---

# Read the workspace operating picture

`GET /account/summary`

## Request

- Base URL: `https://inkseal.net/api/v1`
- URL: `https://inkseal.net/api/v1/account/summary`
- Auth: HTTP bearer

The workspace's operating picture in one call: credit balance, document count, envelope counts by outcome, and the five newest documents with the envelope each one produced.

This is the other half of the agent control plane. An agent polls it to answer the questions it would otherwise ask across four endpoints: can I afford to send, how much is outstanding, what did I upload last, and did any of it complete. It runs the same query the dashboard runs, so an agent and a human never disagree about how many envelopes are in flight.

The counts mean specific things:

- `documents.total`: every document the workspace owns, whether or not it has an envelope.
- `documents.pending`: envelopes in flight, which is `pending` plus `completing`.
- `documents.completed`: envelopes that finished signing.
- `documents.sent`: every envelope that ever left the workspace: in flight, completed, declined, voided, and expired. It is deliberately not `pending + completed`, because a voided envelope was still sent and was still charged for.

`credits.balance` and `credits.policy` mirror `GET /credits/balance` rather than restating them, so one field name carries the balance across the whole API. An `unmetered` workspace spends nothing per send and is never refused for credits.

Documents are named by public identifier only. No row ids and no storage keys appear here, and the workspace comes from the credential's binding, so nothing in the request can point this at another tenant.

## Response `200`

The workspace's balance, counts, and newest documents.

- object
  - `data` AccountSummary, required: The workspace's operating picture: balance, counts, and the newest documents.
    - `credits` object, required
      - `balance` integer, required: The workspace's credit balance. The same number `GET /credits/balance` reports.
      - `policy` 'metered' | 'unmetered', required: How the workspace pays for sends. The same value `GET /credits/balance` reports.
    - `documents` object, required: Document and envelope counts for the whole workspace.
      - `total` integer, required: Every document the workspace owns, including ones with no envelope.
      - `pending` integer, required: Envelopes in flight: status `pending` plus status `completing`.
      - `sent` integer, required: Every envelope that ever left the workspace: in flight, completed, declined, voided, and expired. Deliberately not `pending + completed`, because a voided envelope was still sent.
      - `completed` integer, required: Envelopes where every signer has signed.
    - `recentDocuments` AccountRecentDocument[], required: The five newest documents, newest first, each with the envelope it produced if it has one.
      - `id` string, required: The document's public identifier, usable with the `/documents` endpoints.
      - `filename` string, required: The filename as uploaded.
      - `envelope` object, nullable, required: The envelope created from this document, or null when the document has not been sent for signature.
        - `id` string, required: The envelope's public identifier.
        - `status` 'draft' | 'sending' | 'pending' | 'completing' | 'completed' | 'declined' | 'voided' | 'expired' | 'null', nullable, required: Where the envelope is in its journey to execution.
        - `createdVia` string, nullable, required: How the envelope came into being: `web` from the dashboard, `email` from the inbound-mail agent, `api` from this API. Null on rows written before the field existed.
      - `createdAt` string, date-time, required: When the document was uploaded.

## Other responses

- `401`: The credential is missing, malformed, unknown, expired, revoked, or past its rotation grace window. Code: `unauthorized`. Every authentication failure is deliberately indistinguishable.
- `403`: The credential is valid but may not do this. Codes: `insufficient_scope` (the route's scopes are not all held; `details` names `requiredScopes` and `missingScopes`), `forbidden` (the capability check on the resolved resource failed), `scope_escalation` (a grant wider than the caller's own was requested).
- `429`: A limit was reached. Codes: `rate_limited` (the credential's per-bucket HTTP limit, or the per-workspace detection throttle), `workspace_limit_exceeded` (a workspace content or send limit; `details.limit` names it), `daily_budget_exceeded` (the workspace's daily detection budget). The four rate-limit headers are sent on this response and on no successful one, so a client cannot read its remaining budget without being refused. Retrying after `Retry-After` is always safe: a rate-limit refusal happens before the handler runs.
- `503`: A dependency the request needs is unreachable and nothing was changed. Codes: `queue_unavailable` (a background job could not be enqueued; retry the call), `billing_unavailable` (Stripe would not open a checkout session; nothing was charged, retry the call), `service_unavailable` (the rate-limit store is down, so the request was refused before running).

---

[API](https://skmtc.dev/inkseal/apis/inkseal-api.md) · [All operations](https://skmtc.dev/inkseal/apis/inkseal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inkseal/apis/inkseal-api/revisions/c440c981d578?raw)