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

# Usage and logs

> Read your balance, limits and spend over time, list billed calls with their cost, and look up one call by its request ID. These calls are free.

These calls are free and need a key. Amounts are in dollars. Use the dollar fields, not the older ones beside them.

## Limits and balance

```bash theme={null}
curl https://api.stophy.dev/v1/limits -H "Authorization: Bearer $STOPHY_API_KEY"
```

| Field in `data` | Meaning |
| - | - |
| `tier` | `free` until your first top-up, then `paid` |
| `balanceUsd` | What is left, in dollars |
| `rateLimit` | `limitPerMinute`, `remaining` (counting this call) and `resetsAt`. `null` when the counter is unavailable. |
| `perMinute` | Limits for `calls`, `jobs`, `interact` and `reads` |
| `concurrency` | Calls allowed at once and running now |
| `jobsAtOnce`, `queuedJobs` | Jobs that may run and wait |
| `sessionsAtOnce` | Open browser sessions allowed |
| `paidLimits` | The \$10 step's limits, shown on `free`. `null` on `paid`. |
| `keyExpiresAt` | When the key stops working, or `null` |
| `billingUrl` | Where to add money |

The call counts toward the per-minute limit. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md).

## Usage

`GET /v1/usage` returns `balanceMicros` (millionths of a dollar), `costUsd` for all your calls and `requestCount` of paid calls. It has no `success` or `data` wrapper.

`GET /v1/usage/history` takes these parameters. Read the window in `data.from` and `data.to`, the sum in `data.totals` and the rows in `data.buckets` (`start`, `costUsd`, `requests`).

| Parameter | Default | Meaning |
| - | - | - |
| `interval` | `day` | `hour`, `day` or `month` |
| `from` | 2, 30 or 366 days before `to` for `hour`, `day`, `month` | Start of the window, an ISO time such as `2026-11-01` |
| `to` | Now | End of the window, not included |
| `endpoint` | All | One endpoint, such as `scrape` |
| `apiKeyId` | All | One key |

The window spans at most 31 days for `hour` and 366 for `day` and `month`, and `from` must be before `to`, or the call answers `invalidRequest`. `start` is the UTC start of the bucket. Buckets with no paid calls are left out.

`GET /v1/team/credit-usage` returns `balanceUsd`. Its plan and period fields are `null`. `/historical` returns `periods`, one per month, with `startDate`, `endDate`, `totalCostUsd` and `costUsd`. Add `byApiKey=true` to split each month by key, named in `apiKey`.

## List calls

```bash theme={null}
curl "https://api.stophy.dev/v1/logs?days=1&endpoint=scrape" -H "Authorization: Bearer $STOPHY_API_KEY"
```

`GET /v1/logs` returns `logs`, newest first, 50 a page, with `page`, `pageSize`, `total`, `totalPages` and the `endpoints` you can filter by. Each row has `id`, `requestId`, `createdAt`, `endpoint`, `costUsd`, the key, the HTTP method and status.

| Parameter | Default | Meaning |
| - | - | - |
| `days` | 7 | How far back, 1 to 90 |
| `page` | 0 | Page number, from 0 |
| `apiKeyId` | All | One key |
| `endpoint` | All | One endpoint ID, such as `crawl` |

Only billed calls are logged. A free call, an error and an empty result have no entry, and a billed [zero data retention](https://docs.stophy.dev/production/zero-data-retention.md) call does. Rows hold billing fields, not content. Logs are kept for 90 days.

`GET /v1/logs/{id}` takes the `X-Request-ID` of any answer, looks back `days` days (7 by default, up to 90) and returns `data.costUsd`. `charges` counts how often the call was charged: a crawl or batch charges once per page. An ID not billed in that time answers `404` `notFound`.

`GET /v1/team/activity` returns the same calls with a cursor. Each row has `id`, `endpoint`, `api_version` and `created_at`. Parameters: `endpoint`, `limit` (1 to 100, default 50) and `cursor`. Stop when `has_more` is `false`.

## Jobs and model use

`GET /v1/team/queue-status` returns `activeJobsInQueue`, `waitingJobsInQueue`, `jobsInQueue`, `maxConcurrency` for your tier and `mostRecentSuccess`, the finish time of your last billed call.

`GET /v1/team/token-usage` has older field names ending in `Tokens`. The values count billed amounts, not model tokens. Read `tokensUsed`, `byEndpoint` and `usedSince`. `/historical` returns one row per month, split by key with `byApiKey=true`.

Save the `X-Request-ID` of every call you care about. It is on every answer and in every error body, and [feedback](https://docs.stophy.dev/production/agent-feedback.md) takes it too. See [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md).


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