> ## Documentation Index
> Fetch the complete documentation index at: https://docs.examino.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Credits and Billing in Examino - Full Guide

> Learn how Examino credits are calculated, how to check your balance, and how to transfer credits between teams in your hierarchy using the API.

Credits are the currency Examino uses for AI-powered grading. Every time you launch a correction, Examino reserves credits before processing begins and confirms the charge once each copy is graded. Understanding how credits are counted, and how they flow through your team hierarchy, helps you plan capacity and avoid failed launches.

## How credits are calculated

Examino charges **1 credit per started 20-page block per copy**. Fractional blocks round up, so a 12-page copy costs 1 credit and a 45-page copy costs 3. Page count is determined from the uploaded file at the moment correction is launched.

<CardGroup cols={3}>
  <Card title="1–20 pages" icon="file">
    **1 credit** per copy
  </Card>

  <Card title="21–40 pages" icon="files">
    **2 credits** per copy
  </Card>

  <Card title="41–60 pages" icon="copy">
    **3 credits** per copy
  </Card>
</CardGroup>

<Note>
  Re-running correction on a copy that already has `status: "success"` is **free**. Examino only charges credits for copies that are newly processed in each correction launch.
</Note>

## Credit balance inheritance

Teams in Examino are organised in a hierarchy. If a team has no direct credit balance, it automatically draws from its **nearest ancestor** that holds a balance. This lets institutions allocate credits at the faculty or institution level and let departments consume from that shared pool without manual top-ups at every node.

## Check your balance

Use `GET /api/v1/credits` with the `credits:read` scope to fetch the available balance for any team you administer.

```bash title="Check credit balance" theme={null}
curl "https://app.examino.ai/api/v1/credits?teamId=d4e5f6a7-b8c9-40d1-a2b3-c4d5e6f7a8b9" \
  -H "Authorization: Bearer $EXAMINO_API_KEY"
```

```json title="Response" theme={null}
{
  "teamId": "d4e5f6a7-b8c9-40d1-a2b3-c4d5e6f7a8b9",
  "availableCredits": 1840
}
```

<Tip>
  Check your balance before every correction launch, especially for large exams. The correction endpoint returns `422 INSUFFICIENT_CREDITS` if you don't have enough, verifying upfront avoids a failed launch and makes your pipeline easier to debug.
</Tip>

## Transfer credits between teams

If you need to redistribute credits across your hierarchy, use `POST /api/v1/credits/transfers`. This endpoint requires the `credits:write` scope.

```bash title="Transfer credits" theme={null}
curl -X POST https://app.examino.ai/api/v1/credits/transfers \
  -H "Authorization: Bearer $EXAMINO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromTeamId": "d4e5f6a7-b8c9-40d1-a2b3-c4d5e6f7a8b9",
    "toTeamId":   "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "amount": 500
  }'
```

```json title="Response" theme={null}
{
  "transferId": "tx-9900aabb-ccdd-eeff-0011-223344556677",
  "fromTeamId": "d4e5f6a7-b8c9-40d1-a2b3-c4d5e6f7a8b9",
  "toTeamId":   "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "amount": 500,
  "fromAvailableCredits": 1340,
  "toAvailableCredits":   620
}
```

The response includes the updated balances for **both** teams so you can confirm the transfer in a single call.

<Note>
  Transfers and correction charges are attributed to the exact API key that initiated them, never to the user who created that key. Administrators can inspect the key name and public prefix in the credit ledger; regular organization members only see that the operation came from the API.
</Note>

## Transfer rules

Not all transfers are permitted. The three rules below define when a transfer succeeds and what error you receive when it doesn't.

<AccordionGroup>
  <Accordion title="Transfers must follow the team hierarchy">
    You can only transfer credits between a team and one of its **direct or indirect descendants**, in either direction. Sibling teams (teams that share a common parent but are not in an ancestor–descendant relationship with each other) cannot transfer credits directly.

    Attempting a sibling-to-sibling transfer returns:

    ```json theme={null}
    {
      "status": 422,
      "error": "unprocessable",
      "reason": "notRelated"
    }
    ```
  </Accordion>

  <Accordion title="Both teams must be inside the key scope">
    The source and destination teams must both be inside the API key's team subtree. Authorization is based on the key itself, not on the user who originally created it. If either team is outside the key scope, the API returns `404 not_found` without revealing whether that team exists.
  </Accordion>

  <Accordion title="The source team must have sufficient balance">
    Transfers are **atomic**, Examino never partially debits the source team. If `fromTeamId` does not hold enough credits to cover `amount`, the entire transfer is rejected:

    ```json theme={null}
    {
      "status": 422,
      "error": "unprocessable",
      "reason": "insufficient"
    }
    ```

    Check the source balance with `GET /api/v1/credits` before submitting large transfers to avoid this error.
  </Accordion>
</AccordionGroup>

## Correction launch and credit checks

When you call `POST /exams/{examId}/corrections`, Examino validates your credit balance before reserving anything. If the team (including any ancestor balance) cannot cover the cost of all pending copies, the launch is rejected with a `422 INSUFFICIENT_CREDITS` error and no credits are consumed.

<Warning>
  A rejected launch does **not** create a partial correction. You must add credits and resubmit, use a new `idempotencyKey` if you change the correction scope, or reuse the same key if the request is identical.
</Warning>