---
title: "List user checkpoints"
method: GET
path: "/v2/checkpoints"
tags: ["Checkpoints"]
---

# List user checkpoints

`GET /v2/checkpoints`

## Request

- Base URL: `https://api.runta.com`
- URL: `https://api.runta.com/v2/checkpoints`
- Auth: HTTP bearer

Returns only user-created checkpoints.

## Query parameters

- `limit` integer: Maximum number of checkpoints to return.
- `after` string: Opaque cursor returned by the previous page.

## Response `200`

List response envelope.

- ListCheckpointsResponse: List response envelope.
  - `data` Checkpoint[], required
    - `kind` string: Canonical checkpoint kind, full or cold. Absent on older servers.
    - `display_name` string, required: User-chosen display name.
    - `id` string, required: Stable checkpoint UUID.
    - `created_at` string, required: RFC3339 timestamp when the control-plane checkpoint row was created.
    - `resources` RuntimeResources, required: Runtime resource requests and limits.
      - `current` RuntimeResourceCurrent, required: Current runtime resource allocation.
        - `memory_mib` integer, required: Current memory allocation in MiB.
        - `observed_disk_gib` integer, required: Worker-observed overlay virtual capacity in GiB.
      - `limits` RuntimeResourceLimits, required: Runtime resource limits.
        - `memory_mib` integer, required: Maximum memory in MiB.
      - `requests` RuntimeResourceRequests, required: Runtime resource requests.
        - `memory_mib` integer, required: Requested baseline memory in MiB.
        - `vcpus` integer, required: Requested virtual CPUs.
        - `disk_gib` integer, required: Target overlay virtual capacity in GiB.
    - `state` 'creating' | 'ready' | 'failed', required: Checkpoint lifecycle state.
    - `safe_error_code` string, nullable: Bounded non-sensitive reason when checkpoint creation failed.
    - `source_runtime` CheckpointSourceRuntime: Source runtime lineage for a checkpoint.
      - `id` string, nullable, required: Stable runtime UUID. Null after the source runtime is deleted.
      - `name` string, required: Runtime name captured when the checkpoint was created.
  - `pagination` CheckpointPagination, required: Cursor pagination metadata.
    - `next_cursor` string, nullable, required: Opaque cursor for the next page, or null when this page is complete.
    - `has_more` boolean, required: Whether another page is available.

## Other responses

- `401`: Missing, malformed, or rejected bearer token
- `403`: The bearer token is not allowed to perform this action
- `404`: The requested resource was not found
- `409`: The request conflicts with current resource state
- `422`: Validation or application error
- `429`: Rate limit exceeded
- `501`: Operation is not implemented
- `503`: Upstream service is unavailable
- `504`: Upstream request timed out
- `default`: Error response

## Changes

- **2026-11-05** `fb5a0ecd3fc2`: 20 warning
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `401`
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `403`
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `404`
  - added the new `FEATURE_TEMPORARILY_DISABLED` enum value to the `error/code` response property for the response status `409`
  - …16 more

[Operation history](https://skmtc.dev/runta/apis/runta-public-rest-api/changes/v2/checkpoints/get.md)

---

[API](https://skmtc.dev/runta/apis/runta-public-rest-api.md) - [All operations](https://skmtc.dev/runta/apis/runta-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runta/apis/runta-public-rest-api/revisions/fb5a0ecd3fc2?raw)