Pagination and IDs

Paging through lists

List endpoints take two query parameters: limit, the maximum number of items to return, and offset, the number of items to skip from the start of the list. offset defaults to 0. Alongside the items, every list response carries a cursor object:

{
  "training_runs": [
    {
      "training_run_id": "run_3Bz",
      "base_model": "Qwen/Qwen3-8B",
      "status": "ready"
    }
  ],
  "cursor": { "offset": 0, "limit": 20, "total_count": 41 }
}

The collection key is named for the resource (data for files, training_runs for training runs); the cursor object behaves the same everywhere. To fetch everything, advance offset by the number of items each page returns, and stop once offset plus the returned count reaches total_count:

import requests

runs = []
offset = 0
while True:
    resp = requests.get(
        'https://api.nucleus-ai.io/v1/training-runs',
        headers={'Authorization': f'Bearer {API_KEY}'},
        params={'limit': 20, 'offset': offset},
    )
    body = resp.json()
    page = body['training_runs']
    runs.extend(page)
    offset += len(page)
    if offset >= body['cursor']['total_count']:
        break

Object ID prefixes

Every object ID starts with a prefix naming its type, so an ID in a log line or an error message tells you what it refers to and which endpoint retrieves it.

One thing that looks like an ID but is not: checkpoint paths such as nucleus://run_3Bz:train:0/sampler_weights/000240 are addresses, not IDs. They locate a set of weights within a run rather than naming an API object, and several endpoints accept them directly where weights are expected. See Architecture.