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

# Idempotency & Pagination

> Build reliable Starfire AI API clients using retry-safe state-changing requests and pagination patterns for large resource collections.

# Idempotency & pagination

Reliable API clients need to handle network retries and large result sets without creating duplicate work or silently missing resources.

## Idempotency

A network timeout does not prove Starfire failed to create a run, build, or other durable resource. Retrying a state-changing request blindly can create duplicates.

Where the active v1 contract supports idempotency:

1. Generate a stable idempotency value for one logical operation.
2. Send it using the documented request mechanism.
3. Reuse the same value only when retrying that same logical operation.
4. Generate a new value for a genuinely new operation.

Good candidates include:

* build creation
* long-running run creation
* other expensive/durable create actions

## Read before recreating

If an ambiguous failure returns a request/resource ID, check the resource state before creating another copy.

## Pagination

Large collections such as logs, runs, artifacts, or usage records should be paginated.

The active API can use cursor-style or another documented pagination contract. Treat returned continuation values as opaque; do not construct your own cursor by guessing internal IDs.

## Stable filters

When paging through a collection, keep filters/sort consistent unless you intentionally begin a new listing operation.

## Changing data

Collections can change while you paginate. For audit/reporting tasks that need a stable time range, filter by timestamps or other documented boundaries rather than assuming the collection is frozen during the listing.

## Retries and page requests

Read-only page retrieval can generally be retried after temporary failures according to rate-limit/error guidance. Do not restart from page one unless your application actually needs to rebuild the result set.

<Note>
  The exact idempotency header/field and pagination response fields belong to the active OpenAPI contract. This page defines client behavior, not an undocumented wire format.
</Note>