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

# Limits and throughput

> Run one finite 0xArchive job with explicit worker, window, retry, request, output, and stop budgets.

Run one historical job that stays inside its request, concurrency, credit, retry, and page budgets, and ends with a clear stop state. The example pulls one hour of Hyperliquid core BTC trades, a window every plan's history reaches, including Free's most recent 30 days.

## Before you start

* Choose one venue and market type, symbol, data family, and time window.
* Read [Rate limits](/rate-limits) for your plan's capacity and [Errors](/errors) for retry behavior.
* Set a worker count, page budget, retry budget, and output path before the first request.
* Keep the API key in the runtime environment and out of job logs.

## Inputs

| Field | Bounded value |
| - | - |
| Route | `/v1/hyperliquid/trades/BTC` |
| Window | `start=$START&end=$END`: the hour that ended one hour ago |
| Page size | `limit=100` |
| Workers | `1` for the first run |
| Retry budget | A finite count for `rate_limited`, transient `5xx`, and network timeouts |
| Stop rule | Window exhausted, page budget reached, or a non-retryable error |

## Steps

<Steps>
  <Step title="Run one baseline request">
    ```bash theme={"theme":"github-dark"}
    END=$(( ($(date +%s) - 3600) * 1000 ))   # one hour ago, in Unix milliseconds
    START=$(( END - 3600 * 1000 ))           # one hour earlier

    curl -sS "https://api.0xarchive.io/v1/hyperliquid/trades/BTC?start=$START&end=$END&limit=100" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    Save the status, row count, request ID, and any `meta.next_cursor` before adding workers.
  </Step>

  <Step title="Set finite workers and pages">
    Give each worker one market, symbol, window, and cursor chain. Stop when the window is exhausted or the page budget is reached. Do not let an agent or scheduler create an unbounded loop.
  </Step>

  <Step title="Apply bounded retries">
    Retry `rate_limited`, transient `5xx`, and network timeouts only within the retry budget, and stop on `insufficient_credits`. [When you reach a limit](/rate-limits#when-you-reach-a-limit) says how long to wait for each.
  </Step>

  <Step title="Widen only after the run is inspectable">
    Compare returned rows, request IDs, latency, retries, and quality state with the inputs. Add symbols or workers only after this run has a clear stop state.
  </Step>
</Steps>

## What a finished run looks like

Every request has a recorded status and request ID. The run ends as complete, partial, or stopped with a reason. A remaining cursor, an exhausted retry budget, or a quality failure is visible in the output rather than hidden by a retry loop.

Write the route, numeric window, page size, worker count, retry budget, and stop rule beside the output. Keep request IDs per page, including failed attempts when the client exposes them.

A capacity limit affects request rate, concurrency, credits, standard replay `speed`, or export volume. It can slow or narrow a job; it does not mean the route or dataset is unavailable.

## If something fails

* `400`, invalid symbols, or invalid parameters: fix the input before another call.
* `401`: repair the key source or `X-API-Key` header.
* `403`: read the exact error for that endpoint, account, and key, and stop unchanged retries.
* `429`: retry `rate_limited` within the budget and stop on `insufficient_credits`, as [When you reach a limit](/rate-limits#when-you-reach-a-limit) describes.
* `5xx` or timeout: retry within budget, then check [Data quality](/data-quality) and stop if the budget is exhausted.
* Page budget reached with a cursor remaining: mark the output partial and resume from the saved cursor under a new bounded run.
* A stale or incomplete quality result: narrow, delay, or mark the output as described in [gap handling](/data-quality#handle-gaps).

## Saved run metadata

```json theme={"theme":"github-dark"}
{
  "run": "btc-trades-throughput-001",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "data_family": "trades",
  "route": "/v1/hyperliquid/trades/BTC",
  "query": {
    "start": "START in Unix ms",
    "end": "END in Unix ms",
    "limit": 100
  },
  "workers": 1,
  "page_budget": "record the finite page count",
  "retry_budget": "record the finite attempt count",
  "request_ids": ["00000000-0000-0000-0000-000000000000"],
  "output": "./artifacts/btc-trades-throughput-001.json",
  "stop_reason": "record the observed completion or stop reason"
}
```

The zero UUID is a shape placeholder only. Replace it with the UUID returned by each response or client wrapper.

## Next step

Follow the cursor through the full window with [Pull historical market data](/guides/historical-market-data).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.