# Usage

Reference for GET /v1/usage. Credits spent today, this week and this month, totals per API and a daily series, for the whole account or one key.

## GET /v1/usage

`GET https://api.primaryapi.com/v1/usage`

Auth: API key with view or full access, or a dashboard session

A spending summary of your account in credits, the same numbers as the dashboard's Usage page. All dates and calendar totals are in UTC; weeks start on Monday.

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `days` | integer | The period: `1`, `7`, `30` (default) or `90` days. |
| `keyId` | string | Only usage of this key. |

### Response

**200 OK**:

| Field | Type | Description |
|---|---|---|
| `periodLabel` | string | `Today` for `days=1`, otherwise `Last N days`. |
| `todayCredits` | number | Credits spent today. |
| `thisWeekCredits` | number | Credits spent this calendar week. |
| `thisMonthCredits` | number | Credits spent this calendar month. |
| `totalRequests` | integer | Requests in the period. |
| `totalCredits` | number | Credits spent in the period. |
| `successRate` | number or null | Succeeded ÷ (succeeded + failed) in the period, from 0 to 1 with four decimals; `null` when no request finished. |
| `byApi` | object[] | Per API: `{ sku, title, requests, credits }`. |
| `daily` | object[] | Per UTC day, oldest first and zero-filled: `{ date, requests, credits }`. |
| `byMember` | object[] | Per workspace member: `{ userId, name, requests, credits, sources }`. Calls from the dashboard count toward the member who ran them; calls with an API key count toward the member who created the key, or claimed it from an agent. `sources` lists each key `{ keyId, name }` by credits spent, with `keyId: null` for dashboard calls. One entry with `userId: null` collects calls nobody is on record for (an unclaimed agent trial key, or a key whose creator deleted their account); it always comes last. |

```bash
curl -sS "https://api.primaryapi.com/v1/usage?days=7" -H "Authorization: Bearer $PRIMARYAPI_VIEW_KEY"
```

```json title="200 OK"
{
  "periodLabel": "Last 7 days",
  "todayCredits": 341,
  "thisWeekCredits": 1490,
  "thisMonthCredits": 9408,
  "totalRequests": 1874,
  "totalCredits": 2218,
  "successRate": 0.993,
  "byApi": [
    { "sku": "email.verify", "title": "Email Verify", "requests": 1530, "credits": 1530 },
    { "sku": "reddit.search", "title": "Reddit Search", "requests": 344, "credits": 688 }
  ],
  "daily": [
    { "date": "2026-10-24", "requests": 212, "credits": 251 },
    { "date": "2026-10-25", "requests": 251, "credits": 296 }
  ],
  "byMember": [
    {
      "userId": "usr_01JBXW8Q4D7F9H1K3M5P7R9T1V",
      "name": "Dev Patel",
      "requests": 1530,
      "credits": 1530,
      "sources": [{ "keyId": "key_01JBXY0D2F4H6K8M0P2R4T6V8X", "name": "support-bot" }]
    },
    {
      "userId": "usr_01JBXW9A2C4E6G8J0L2N4Q6S8U",
      "name": "Lena Ortiz",
      "requests": 344,
      "credits": 688,
      "sources": [
        { "keyId": "key_01JBXZ3B5D7F9H1K3M5P7R9T1W", "name": "Research agent" },
        { "keyId": null, "name": "Playground" }
      ]
    }
  ]
}
```

The numbers are illustrative. For one key's history in the same shape, see [`GET /v1/api-keys/{id}/usage`](/docs/api-reference/keys#get-v1api-keysidusage); for individual calls, [`GET /v1/requests`](/docs/api-reference/requests).
