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

# Get Credit Top-Up

> Poll a credit top-up until the human has paid: PENDING, COMPLETED, EXPIRED, or CANCELED.

Reads one [top-up](/docs/developers/api-reference/credits/create-top-up). Poll it after handing the `checkoutUrl` to your human: `PENDING` means the checkout link has not been paid yet, `COMPLETED` means the credits are available (confirm with [`GET /credits`](/docs/developers/api-reference/credits/balance)).

A `PENDING` top-up past its `expiresAt` flips to `EXPIRED` the next time it is read — expired links cannot be paid; create a new top-up instead. Top-ups belonging to another account return `404`.

**Requirements:** `payments:read` scope + the `public_api_credits` feature. Works pre-claim.

## Request

<ParamField path="topUpId" type="string" required>
  The top-up ID returned when the top-up was created.
</ParamField>

## Response

<ResponseField name="topUp" type="object">
  <Expandable title="top-up" defaultOpen>
    <ResponseField name="id" type="string">
      Top-up ID.
    </ResponseField>

    <ResponseField name="status" type="string">
      `PENDING`, `COMPLETED`, `EXPIRED`, or `CANCELED`.
    </ResponseField>

    <ResponseField name="amountCents" type="number">
      Requested amount in US cents.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO creation timestamp.
    </ResponseField>

    <ResponseField name="completedAt" type="string | null">
      ISO timestamp when payment settled; `null` unless `COMPLETED`.
    </ResponseField>

    <ResponseField name="expiresAt" type="string | null">
      ISO timestamp when the unpaid checkout link lapses.
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | `code`         | Meaning                                                                                             |
| ------ | -------------- | --------------------------------------------------------------------------------------------------- |
| `401`  | `UNAUTHORIZED` | Missing or invalid token                                                                            |
| `403`  | `FORBIDDEN`    | Missing `payments:read` scope, or `public_api_credits` disabled                                     |
| `404`  | `NOT_FOUND`    | No such top-up, or it belongs to another account (`details: {resource: "credit-top-ups", topUpId}`) |

<RequestExample>
  ```bash curl theme={null}
  curl -sS https://app.opentrain.ai/api/public/v1/credits/top-ups/<TOP_UP_ID> \
    -H "Authorization: Bearer $OT_API_TOKEN"
  ```

  ```bash CLI theme={null}
  opentrain credits top-up-status --top-up-id <TOP_UP_ID> --json
  ```

  ```json MCP: opentrain_get_credit_top_up theme={null}
  {
    "topUpId": "<TOP_UP_ID>"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (completed) theme={null}
  {
    "topUp": {
      "id": "<TOP_UP_ID>",
      "status": "COMPLETED",
      "amountCents": 10000,
      "createdAt": "2026-06-12T10:00:00.000Z",
      "completedAt": "2026-06-12T10:12:00.000Z",
      "expiresAt": "2026-06-13T10:00:00.000Z"
    }
  }
  ```

  ```json 200 (still pending) theme={null}
  {
    "topUp": {
      "id": "<TOP_UP_ID>",
      "status": "PENDING",
      "amountCents": 10000,
      "createdAt": "2026-06-12T10:00:00.000Z",
      "completedAt": null,
      "expiresAt": "2026-06-13T10:00:00.000Z"
    }
  }
  ```
</ResponseExample>