# Your balance and recent usage

`GET /v1/usage`

Returns your key's credit balance, rate limit, prices and the last **30 days** of usage, **free**.

- **Auth:** API key ([Authentication](https://installgraph.com/docs/authentication.md))
- **Scope:** none
- **Cost:** Free.

Check it before a large pull, or to reconcile what a job spent.

Free, and needs no scope.

## Request

```bash
curl "https://api.installgraph.com/v1/usage" \
  -H "Authorization: Bearer $INSTALLGRAPH_API_KEY"
```

## Response

`200`. The example's stores are fictional.

```json
{
  "data": {
    "key": {
      "prefix": "sfs_01234567",
      "owner": "you@company.com",
      "name": "Default",
      "scopes": [
        "companies:read",
        "apps:read",
        "events:read"
      ]
    },
    "credits": {
      "balance": 46,
      "unlimited": false
    },
    "rateLimit": {
      "perMinute": 60,
      "remaining": 59,
      "resetAt": "2026-11-06T10:15:00.000Z"
    },
    "prices": {
      "GET /v1/companies/{domain}": {
        "perRequest": 1
      },
      "GET /v1/apps/{slug}/companies": {
        "perRow": 1
      }
    },
    "last30Days": {
      "since": "2026-10-07T10:14:12.000Z",
      "requests": 3,
      "credits": 4,
      "byEndpoint": [
        {
          "endpoint": "GET /v1/apps/{slug}/companies",
          "requests": 1,
          "rows": 2,
          "credits": 2
        },
        {
          "endpoint": "GET /v1/companies/{domain}",
          "requests": 1,
          "rows": 1,
          "credits": 1
        },
        {
          "endpoint": "GET /v1/events",
          "requests": 1,
          "rows": 1,
          "credits": 1
        }
      ]
    },
    "recent": [
      {
        "at": "2026-11-06T10:14:02.000Z",
        "type": "usage",
        "amount": -1,
        "credits": 1,
        "balanceAfter": 46,
        "endpoint": "GET /v1/events",
        "rows": 1,
        "requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
        "note": null
      },
      {
        "at": "2026-11-05T16:20:41.000Z",
        "type": "grant",
        "amount": 25,
        "credits": 25,
        "balanceAfter": 50,
        "endpoint": null,
        "rows": null,
        "requestId": null,
        "note": "Verified email"
      }
    ]
  },
  "meta": {
    "requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
    "creditsUsed": 0,
    "creditsCharged": 0,
    "creditsRemaining": 46,
    "freeRepulls": 0
  }
}
```

### Fields

| Field | Type | Description |
| --- | --- | --- |
| `data.key` | object |  |
| `data.key.prefix` | string | Example: `sfs_Ab12Cd34`. |
| `data.key.owner` | string |  |
| `data.key.name` | string \| null |  |
| `data.key.scopes` | string[] | One of `companies:read`, `apps:read`, `events:read`. |
| `data.credits` | object |  |
| `data.credits.balance` | integer \| null | Null for unlimited keys. |
| `data.credits.unlimited` | boolean |  |
| `data.rateLimit` | object |  |
| `data.rateLimit.perMinute` | integer |  |
| `data.rateLimit.remaining` | integer |  |
| `data.rateLimit.resetAt` | string (date-time) |  |
| `data.prices` | object | Credits per endpoint, `{ perRequest }` or `{ perRow }`. |
| `data.last30Days` | object |  |
| `data.last30Days.since` | string (date-time) |  |
| `data.last30Days.requests` | integer | Billed requests (free ones are not recorded). |
| `data.last30Days.credits` | integer |  |
| `data.last30Days.byEndpoint` | object[] |  |
| `data.last30Days.byEndpoint[].endpoint` | string |  |
| `data.last30Days.byEndpoint[].requests` | integer |  |
| `data.last30Days.byEndpoint[].rows` | integer |  |
| `data.last30Days.byEndpoint[].credits` | integer |  |
| `data.recent` | object[] | The latest 50 ledger entries, newest first. |
| `data.recent[].at` | string (date-time) |  |
| `data.recent[].type` | string | One of `usage`, `grant`, `purchase`, `refund`, `adjustment`. |
| `data.recent[].amount` | integer | Change to the balance. |
| `data.recent[].credits` | integer |  |
| `data.recent[].balanceAfter` | integer \| null |  |
| `data.recent[].endpoint` | string \| null |  |
| `data.recent[].rows` | integer \| null |  |
| `data.recent[].requestId` | string \| null |  |
| `data.recent[].note` | string \| null |  |

Every keyed response also carries `meta` (`requestId`, `creditsUsed`, `creditsRemaining`, `freeRepulls`) and the `X-Credits-*` and `X-RateLimit-*` headers. See [Credits](https://installgraph.com/docs/credits.md) and [Rate limits](https://installgraph.com/docs/rate-limits.md).

## Errors

| Status | Code | Meaning | What to do |
| --- | --- | --- | --- |
| 401 | `missing_api_key` | No key was sent. | Send `Authorization: Bearer sfs_…` or `X-API-Key: sfs_…`. |
| 401 | `invalid_api_key` | The key is not one we issued. | Check for truncation or whitespace; keys are `sfs_` plus 32 letters and digits. |
| 401 | `api_key_revoked` | The key was revoked. | Make a new key at installgraph.com/account. |
| 403 | `insufficient_scope` | The key lacks this endpoint's scope. | Use a key with the scope the endpoint lists (`GET /v1/usage` shows yours). |
| 403 | `api_key_suspended` | The key is suspended. | Talk to us, quoting `requestId`. |
| 429 | `rate_limited` | Too many requests this minute. | Wait `Retry-After` seconds, then retry. |

All codes: [Errors](https://installgraph.com/docs/errors.md).