# 계정 API 참조 — 플랜, 크레딧 및 사용량

> ImageToTable.ai v1 API에 대한 유효 플랜, 역할, 사용 가능 크레딧, SDK가 준수해야 할 제한 한도, 포인트 소비 내역을 확인하세요.

API 키 소유 계정에 대한 두 개의 읽기 전용 엔드포인트입니다. 플랜 및 사용 가능 크레딧에 대한 스냅샷과 셀프 서비스 정산을 위한 페이지별 크레딧 소비 내역을 제공합니다.

## 계정 가져오기

계정의 **유효** 플랜과 크레딧을 반환합니다. 계정이 팀의 구성원인 경우, 개인의 멤버십 플랜이 아닌 팀 소유자의 플랜/크레딧 풀이 이미 반영됩니다.

`GET /api/v1/account`

### 매개변수

없음 — 계정은 `Authorization` 헤더의 API 키로 완전히 결정됩니다.

`max_batch_size` 및 `upload_concurrency`는 클라이언트 SDK가 먼저 `invalid_parameter`/`rate_limit_exceeded` 오류를 통해 이러한 제한을 발견하는 대신 자체 업로드 루프를 자체적으로 제한할 수 있도록 제공됩니다.

### 가능한 오류

- `missing_api_key` / `invalid_api_key` / `plan_required` — [오류 처리](/developers/guides/errors)를 참조하세요.

## 계정 사용량 조회

계정에서 크레딧에 영향을 미치는 모든 이벤트를 최신순으로 페이지네이션하여 보여주는 원장입니다. "이 작업에 크레딧이 얼마나 들었나"를 확인하는 용도로 설계되었으며, UI 구동용이 아닙니다.

`GET /api/v1/account/usage`

### 매개변수

| 이름 | 위치 | 유형 | 설명 |
| --- | --- | --- | --- |
| limit | query, 선택 사항 | integer | 1–200. 기본값 50. |
| batch_name | query, 선택 사항 | string | 원장을 특정 배치의 항목으로 제한합니다. 예: "배치 X에 크레딧이 얼마나 들었나" |
| page_token | query, 선택 사항 | string | 이전 응답의 next_page_token 에서 가져온 불투명 커서입니다. 이 엔드포인트는 최신순 으로 페이지네이션합니다. 토큰은 여전히 불투명하며 동일한 방식으로 왕복되지만, 기본 순서만 다릅니다. 페이지네이션 을 참조하세요. |

`amount`는 부호가 있습니다: 음수는 지출, 양수는 크레딧 반환을 의미합니다. 따라서 한 페이지의 `amount` 값을 합산하면 해당 페이지의 순 변화량을 알 수 있습니다. `document_id`는 [문서](/developers/reference/documents)의 `document_id`와 동일한 ID 공간입니다.

### 가능한 오류

- `missing_api_key` / `invalid_api_key` / `plan_required` — [오류 처리](/developers/guides/errors)를 참조하세요.
- `invalid_parameter` — `limit` 또는 `page_token`이 잘못되었습니다.

## Code Examples

### 계정 가져오기

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

### 응답

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

### 계정 사용량 조회

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

### 응답

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