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

# Overview

> Read your organization's credits and usage from scripts, dashboards, and finance tools, and let any API key check its own limit and spend.

The Management API serves account data from the control plane. It never runs inference: model requests go to the [Inference API](https://platform.pearlresearch.ai/docs/reference/inference), with an inference key.

## Base URL

```text theme={null}
https://api.platform.pearlresearch.ai/api/v1
```

## Authentication

Send a key as a bearer token on every request:

```bash theme={null}
Authorization: Bearer $PEARL_MANAGEMENT_KEY
```

* `GET /credits` and `GET /activity` need a **management key** (`sk-prl-mgmt-`). Org admins create them on the [Management Keys](https://platform.pearlresearch.ai/management-keys) page; the full key is shown once. A management key reads data for its whole organization and cannot call models.
* `GET /key` takes **any API key**, inference keys (`sk-prl-infapi-`) included, and describes the key that calls it. An inference key on any other endpoint gets a `403`.
* A revoked, deleted, or expired key stops working right away and gets a `401`.

## Endpoints

| Endpoint | Key | Description |
| - | - | - |
| [`GET /credits`](/docs/reference/management/credits) | Management | Credits granted to your organization and how much of them is used. |
| [`GET /key`](/docs/reference/management/key) | Any | The calling key's credit limit and when it resets, expiration, and spend. |
| [`GET /activity`](/docs/reference/management/activity) | Management | Usage per day and model over the last 30 completed days. |

```bash Example theme={null}
curl "https://api.platform.pearlresearch.ai/api/v1/credits" \
  -H "Authorization: Bearer $PEARL_MANAGEMENT_KEY"
```

```json Response theme={null}
{
  "data": {
    "total_credits": 150,
    "total_usage": 61.348217
  }
}
```

## Conventions

* A successful response is JSON with the result under `data`.
* Money is USD as a JSON number, rounded to 9 decimal places, so fractions of a cent still show. Sum large sets of figures with a decimal type if you need exact totals.
* Dates are UTC calendar days in `YYYY-MM-DD` format, and timestamps are ISO 8601 in UTC.
* `prompt_tokens` counts every input token, including the ones served from the [prompt cache](https://platform.pearlresearch.ai/docs/prompt-caching); `cached_tokens` is the cached part of it.
* Usage figures match the [Analytics](https://platform.pearlresearch.ai/usage) page. Recent usage can take a few minutes to appear, usage that billing hasn't priced yet counts as 0 until it is, and costs can differ slightly from your final invoice.

## Errors

Every error response is JSON with the HTTP status as `code` and a `message` saying what went wrong:

```json theme={null}
{
  "error": {
    "code": 401,
    "message": "Invalid API key."
  }
}
```

| Status | Meaning |
| - | - |
| `200` | Success. The result is under `data`. |
| `400` | Invalid query parameters (a `date` outside the last 30 completed days, a malformed `api_key_id`, an unknown parameter), or a request covering more usage than one response can return. Fix the request; retrying it unchanged fails again. |
| `401` | Missing, unknown, revoked, or expired key. |
| `403` | An inference key on an endpoint that needs a management key. |
| `429` | Rate limit exceeded. Wait `Retry-After` seconds; see [Rate limits](/docs/reference/management/rate-limits.md). |
| `500` | Unexpected server error. Safe to retry with backoff. |
| `503` | The data isn't ready yet, for example while usage syncs for the first time or a new organization is still being set up. Retry after a few seconds. |

> [!NOTE]
>
> Retry `429`, `500`, and `503` with backoff. A `400`, `401`, or `403` fails the same way until the request or the key changes.


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