> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agency Overview Stats

> Rolled-up messaging stats across every workspace in your Tuco agency, plus a per-workspace breakdown and billing health.

<Note>
  One call for the whole agency: aggregate metrics, a row per workspace, line counts
  and subscription health.
</Note>

## Endpoint

* **Method**: `GET`
* **Path**: `/api/agency/overview`
* **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys))

## Query parameters

| Param | Type | Notes |
| - | - | - |
| `days` | `7` \| `30` \| `90` | Window for the activity metrics. Omitted or invalid → all time. Line counts are current state and are never windowed |

## Example request

```bash theme={null}
curl "https://app.tuco.ai/api/agency/overview?days=30" \
  -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx"
```

## Success response (200)

```json theme={null}
{
  "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx",
  "workspaces": 4,
  "totalLines": 7,
  "metrics": {
    "reached": 1840,
    "sent": 2190,
    "fallback": 61,
    "failed": 12,
    "replied": 143,
    "uniqueReplied": 128,
    "repliedPct": 6.9,
    "positiveReplied": 41,
    "positivePct": 2.2
  },
  "statusCounts": { "active": 3, "attention": 1, "inactive": 0 },
  "series": { "days": 30, "sent": [12, 40, 0, 31] },
  "perWorkspace": [
    {
      "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT",
      "name": "Acme Roofing",
      "legalName": "Acme Roofing LLC",
      "plan": "starter",
      "subscriptionStatus": "active",
      "lines": 2,
      "sent": 814,
      "received": 57,
      "failed": 3,
      "repliedPct": 7.0
    }
  ]
}
```

## Reading it

* `metrics` is the roll-up across every sub-workspace; `perWorkspace` is the same
  computation per workspace, so the rows sum to the totals.
* `statusCounts.attention` counts workspaces in `past_due`, `unpaid`, `incomplete`,
  `incomplete_expired` or `canceled` — the ones whose billing needs you.
* `series.sent` is a daily count for the last `days` calendar days including today,
  for a sparkline.
* An agency with no workspaces yet returns zeros, never another agency's numbers.

## Error responses

| Status | Code | When |
| - | - | - |
| `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key |
| `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used |
| `403` | `NOT_AN_AGENCY` | The account behind the key is not an agency |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.