# Referência da API de Conta — Plano, Créditos e Uso

> Consulte seu plano efetivo, função e créditos disponíveis, os limites de aceleração que seu SDK deve respeitar e seu histórico de consumo de pontos para a API v1 do ImageToTable.ai.

Dois endpoints somente leitura para a conta proprietária da chave de API: um instantâneo do plano e dos créditos disponíveis (com os dois números que um SDK precisa para se autorregular) e um registro paginado do consumo de créditos para reconciliação por autoatendimento.

## Obter conta

Retorna o plano e os créditos **efetivos** da sua conta — se sua conta for membro de uma equipe, isso já reflete o plano/pool de créditos do proprietário da equipe, não seu plano de associação individual.

`GET /api/v1/account`

### Parâmetros

Nenhum — a conta é determinada inteiramente pela chave de API no cabeçalho `Authorization`.

`max_batch_size` e `upload_concurrency` são fornecidos para que um SDK cliente possa autorregular seu próprio loop de upload em vez de descobrir esses limites ao encontrar erros `invalid_parameter`/ `rate_limit_exceeded` primeiro.

### Erros possíveis

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulte [Tratamento de Erros](/developers/guides/errors).

## Obter uso da conta

Um registro paginado (do mais recente ao mais antigo) de cada evento que afeta seus créditos na conta — deduções de extração, deduções de anotação de bbox e reembolsos. Criado para reconciliar "quantos créditos isso me custou", não para alimentar uma interface (compare com as strings de exibição pré-formatadas de `/profile/usage_history`, que este endpoint não retorna — você recebe valores `amount` estruturados e com sinal).

`GET /api/v1/account/usage`

### Parâmetros

| Nome | Localização | Tipo | Descrição |
| --- | --- | --- | --- |
| limit | query, opcional | inteiro | 1–200. Padrão 50. |
| batch_name | query, opcional | string | Restringir o registro a entradas de um lote — "quantos créditos o lote X me custou." |
| page_token | query, opcional | string | Cursor opaco de um next_page_token de resposta anterior. Este endpoint pagina do mais recente ao mais antigo (diferente de outros endpoints de listagem v1, que paginam do mais antigo ao mais recente) — o token continua opaco e faz o mesmo percurso de ida e volta, apenas a ordem subjacente difere. Consulte Paginação . |

`amount` tem sinal: negativo para gastos (deduções de extração/bbox), positivo para créditos de volta (reembolsos/reembolsos de cancelamento) — então somar os valores de `amount` de uma página fornece a variação líquida naquela página. `document_id` está no mesmo espaço de ID que o `document_id` de [Documentos](/developers/reference/documents) (o registro interno chama de `task_id`; este endpoint renomeia para consistência com o resto da v1).

### Possíveis erros

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulte [Tratamento de Erros](/developers/guides/errors).
- `invalid_parameter` — `limit` ou `page_token` inválido.

## Code Examples

### Obter conta

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());
```

### Resposta

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

### Obter uso da conta

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());
```

### Resposta

```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/pt/developers/reference/account