# Referencia de la API de Cuenta — Plan, Créditos y Uso

> Consulte su plan efectivo, rol y créditos disponibles, los límites de limitación que su SDK debe respetar y su historial de consumo de puntos para la API v1 de ImageToTable.ai.

Dos endpoints de solo lectura para la cuenta propietaria de la clave API: una instantánea del plan y los créditos disponibles (con los dos números que un SDK necesita para autolimitarse) y un libro de contabilidad paginado del consumo de créditos para la conciliación de autoservicio.

## Obtener cuenta

Devuelve el plan y los créditos **efectivos** de su cuenta — si su cuenta es miembro de un equipo, esto ya refleja el plan/fondo de créditos del propietario del equipo, no su propio plan de membresía individual.

`GET /api/v1/account`

### Parámetros

Ninguno — la cuenta se determina completamente por la clave API en el encabezado `Authorization`.

`max_batch_size` y `upload_concurrency` se proporcionan para que un SDK cliente pueda autolimitar su propio bucle de subida en lugar de descubrir estos límites al toparse primero con errores `invalid_parameter`/ `rate_limit_exceeded`.

### Posibles errores

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

## Obtener uso de la cuenta

Un registro paginado (del más reciente al más antiguo) de cada evento que afecta sus créditos en la cuenta: deducciones por extracción, deducciones por anotación de bbox y reembolsos. Diseñado para conciliar "¿cuántos créditos me costó esto?", no para manejar una interfaz de usuario (compare con las cadenas de visualización preformateadas de `/profile/usage_history`, que este endpoint no devuelve; en su lugar, obtiene valores `amount` estructurados con signo).

`GET /api/v1/account/usage`

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| limit | consulta, opcional | entero | 1–200. Valor predeterminado: 50. |
| batch_name | consulta, opcional | cadena | Restringe el registro a entradas de un lote: "cuántos créditos me costó el lote X". |
| page_token | consulta, opcional | cadena | Cursor opaco de un next_page_token de una respuesta anterior. Este endpoint pagina del más reciente al más antiguo (a diferencia de otros endpoints de listado v1, que pagan del más antiguo al más reciente); el token sigue siendo opaco y se envía de la misma manera, solo difiere el orden subyacente. Consulte Paginación . |

`amount` tiene signo: negativo para gastos (deducciones por extracción/bbox), positivo para créditos devueltos (reembolsos/reembolsos por cancelación); así, sumar los valores `amount` de una página le da el cambio neto en esa página. `document_id` está en el mismo espacio de ID que el `document_id` de [Documentos](/developers/reference/documents) (el registro interno lo llama `task_id`; este endpoint lo renombra para mantener la coherencia con el resto de v1).

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulte [Manejo de errores](/developers/guides/errors).
- `invalid_parameter` — `limit` o `page_token` incorrectos.

## Code Examples

### Obtener cuenta

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

### Respuesta

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

### Obtener uso de la cuenta

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

### Respuesta

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