# Status

Check API access, credit balance, and usage metering

> Section: Guides

> Last updated: **2026-10-17**.

> API version: **v1 (Latest)**. OpenAPI publication: **2026-11-08**.

## `GET /v1/status`

Check API access, credit balance, and metering. Check your key's data mode and remaining request allowances before requesting research data.

Lifecycle: **stable**. Availability: **released**. Authentication: **Bearer API key**.

## Examples

Requires a Bearer API key. Replace `<api-key>` in each request with your developer key. Free.

Response excerpts below illustrate the shape only; placeholders and empty arrays are not live research or proof of coverage. Actual responses include additional fields.

### Check API access and credits

Check whether your API key can access research, along with available credit and request allowances.

```bash
curl --request GET \
  --url 'https://beliefstate.ai/v1/status' \
  --header 'Authorization: Bearer <api-key>'
```

Response excerpt:

```json
{
  "status": "ready",
  "currency": "usd",
  "balanceCents": null
}
```

This authenticated check is free. A null balance means unavailable, not zero. The request does not purchase credits or change your plan.

## Request

```bash
curl --request GET \
  --url 'https://beliefstate.ai/v1/status' \
  --header 'Authorization: Bearer <api-key>'
```

```javascript
const options = { method: "GET", headers: {"Authorization":"Bearer <api-key>"} };

fetch("https://beliefstate.ai/v1/status", options)
  .then((response) => response.json())
  .then((data) => console.log(data));
```

```python
import requests

url = "https://beliefstate.ai/v1/status"
headers = {"Authorization":"Bearer <api-key>"}

response = requests.get(url, headers=headers)
print(response.text)
```

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Request-ID` | header | `string` | no | Stable ID for an idempotent retry. Reuse it only for the same logical request. |

## Response includes

- Access and data mode
- Metering state
- Available balance and currency when applicable

## Response schemas

### 200 Successful read only response

- `accessMode` (live | local_live | preview, required)
- `balanceCents` (integer, required)
- `catalogVersion` (string | null, required)
- `currency` (string, required)
- `dataMode` (live | preview, required)
- `metering` (active | disabled, required)
- `prepaidRequestsRemaining` (integer, required)
- `status` ("ready", required)
- `subscriptionPlan` (string | null, required)
- `subscriptionRequestsRemaining` (integer, required)

### 400 Invalid input

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 401 Authentication failed

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 402 Paid access required

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 404 Security unavailable

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 409 Duplicate request ID

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

### 503 Stored intelligence temporarily unavailable

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `recovery` (string | null, required)
  - `retryable` (boolean, required)

## Agent feedback

Report unclear, stale, or incorrect documentation through [BeliefState support](https://beliefstate.ai/contact). Include this page URL and the smallest reproducible detail.

<!-- BeliefState-Origin: https://beliefstate.ai/docs/api/status; Content-Fingerprint: bs-sha256-1e5f6700769d4b66f43ff101306c1212c046584443ad200ed26ed258ee3402c1 -->