# Account API Reference — Plan, Credits & Usage

> Check your effective plan, role, and available credits, the throttling limits your SDK should respect, and your point-consumption history for the ImageToTable.ai v1 API.

Two read-only endpoints for the API key's owning account: a snapshot of plan and available credits (with the two numbers an SDK needs to throttle itself), and a paginated ledger of credit consumption for self-service reconciliation.

## Get account

Returns your account's **effective** plan and credits — if your account is a member of a Team, this already reflects the team owner's plan/credit pool, not your own individual membership_plan.

`GET /api/v1/account`

### Parameters

None — the account is determined entirely by the API key in the `Authorization` header.

`max_batch_size` and `upload_concurrency` are provided so a client SDK can self-throttle its own upload loop instead of discovering these limits by hitting `invalid_parameter`/ `rate_limit_exceeded` errors first.

### Possible errors

- `missing_api_key` / `invalid_api_key` / `plan_required` — see [Error Handling](/developers/guides/errors).

## Get account usage

A paginated, newest-first ledger of every credit-affecting event on your account — extraction deductions, bbox-annotation deductions, and refunds. Built for reconciling "how many credits did this cost me," not for driving a UI (compare `/profile/usage_history`'s pre-formatted display strings, which this endpoint does not return — you get structured, signed `amount` values instead).

`GET /api/v1/account/usage`

### Parameters

| Name | Location | Type | Description |
| --- | --- | --- | --- |
| limit | query, optional | integer | 1–200. Default 50. |
| batch_name | query, optional | string | Restrict the ledger to entries for one batch — "how many credits did batch X cost me." |
| page_token | query, optional | string | Opaque cursor from a previous response's next_page_token . This endpoint paginates newest-first (unlike other v1 list endpoints, which paginate oldest-first) — the token is still opaque and round-trips the same way, only the underlying order differs. See Pagination . |

`amount` is signed: negative for spends (extraction/bbox deductions), positive for credits back (refunds/cancellation refunds) — so summing a page's `amount` values gives you the net change over that page. `document_id` is the same ID space as [Documents](/developers/reference/documents)' `document_id` (the internal ledger calls it `task_id`; this endpoint renames it for consistency with the rest of v1).

### Possible errors

- `missing_api_key` / `invalid_api_key` / `plan_required` — see [Error Handling](/developers/guides/errors).
- `invalid_parameter` — bad `limit` or `page_token`.

## Code Examples

### Get account

GET /api/v1/account

**cURL**

```bash
curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/account", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Response

```json
{
  "plan": "Pro",
  "role": "User",
  "available_credits": 842,
  "max_batch_size": 200,
  "upload_concurrency": 4
}
```

### Get account usage

GET /api/v1/account/usage

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/account/usage?batch_name=july-invoices&limit=50" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/account/usage",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"batch_name": "july-invoices", "limit": 50},
)
print(response.json())
```

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/account/usage");
url.searchParams.set("batch_name", "july-invoices");
url.searchParams.set("limit", "50");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Response

```json
{
  "data": [
    {
      "id": 88213,
      "action": "deduction",
      "batch_name": "july-invoices",
      "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
      "point_type": "personal",
      "amount": -1,
      "consumer_id": 501,
      "created_at": "2026-07-16T09:12:05+00:00"
    },
    {
      "id": 88190,
      "action": "refund",
      "batch_name": "june-receipts",
      "document_id": "1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901",
      "point_type": "personal",
      "amount": 1,
      "consumer_id": 501,
      "created_at": "2026-07-15T14:02:11+00:00"
    }
  ],
  "has_more": true,
  "next_page_token": "eyJpZCI6ODgxOTB9"
}
```

---

Source: https://imagetotable.ai/developers/reference/account