Pagination & filtering

List endpoints that can return many records — such as transactions and orders — accept query parameters to page through results, filter them down, and sort them. This guide walks through doing all three against a real endpoint.

Before you start, make sure you can authenticate. Every request needs a valid Authorization: Bearer <token> header (15-minute OAuth access tokens from POST /oauth/token) and a User-Agent: product/version header. See Get started for the basics.

1. Know the pagination parameters

tastytrade list endpoints use offset-based pagination with two query parameters:

Both keys are dasherized, like all tastytrade query keys. Responses follow the standard envelope: a data object containing an items array, plus a context field echoing the request path. Paginated list responses also include a top-level pagination block describing the current page (per-page, page-offset, item-offset, total-items, total-pages, current-item-count).

2. Request the first page

Use GET /accounts/{account_number}/transactions as the example. Substitute your real account_number, and use the sandbox host https://api.cert.tastyworks.com while testing (production is https://api.tastyworks.com).

curl "https://api.cert.tastyworks.com/accounts/{account_number}/transactions?page-offset=0&per-page=250" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-custom-client/1.0" \
  -H "Accept: application/json"

A successful response looks like:

{
  "data": {
    "items": [
      { "id": 123, "transaction-type": "Trade" }
    ]
  },
  "context": "/accounts/{account_number}/transactions",
  "pagination": {
    "per-page": 250,
    "page-offset": 0,
    "item-offset": 0,
    "total-items": 1622,
    "total-pages": 7,
    "current-item-count": 250
  }
}

3. Iterate until the collection is exhausted

Walk forward one page at a time, incrementing page-offset by 1 on each request while keeping per-page constant:

1. Request page-offset=0.
2. Process every entry in data.items.
3. Use the pagination block to decide when to stop: you are on the last page when page-offset + 1 >= pagination.total-pages (equivalently, when current-item-count is less than per-page). As a fallback, if a response has no pagination block, stop when items comes back with fewer than per-page entries (or empty).
4. Otherwise increment page-offset and repeat.

# page 2 (the second page of 250)
curl "https://api.cert.tastyworks.com/accounts/{account_number}/transactions?page-offset=1&per-page=250" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-custom-client/1.0"

Keep per-page modest and page steadily rather than hammering the endpoint — a burst of rapid requests can earn an HTTP 429. See Rate limits and backoff.

4. Sort the results

The sort parameter controls ordering. It accepts Desc or Asc and defaults to Desc (newest first):

curl "https://api.cert.tastyworks.com/accounts/{account_number}/transactions?sort=Asc&per-page=250" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-custom-client/1.0"

5. Narrow results with filters

Filtering server-side returns fewer pages and less data to walk. The transactions endpoint supports filters such as:

Some filters accept multiple values as an array. Per tastytrade conventions, repeat the key with [], e.g. types[]=Trade&types[]=Money%20Movement (URL-encode values that contain spaces). Note that type and types[] are mutually exclusive — supply one or the other, not both:

curl "https://api.cert.tastyworks.com/accounts/{account_number}/transactions?start-date=2024-01-01&end-date=2024-01-31&instrument-type=Equity&types[]=Trade&per-page=250" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "User-Agent: my-custom-client/1.0"

Filters, sorting, and pagination combine freely in a single request. Orders behave the same way — GET /accounts/{account_number}/orders accepts the same page-offset, per-page, and sort parameters plus its own filters like status, start-date, and underlying-symbol.

Errors

A malformed page or filter value returns HTTP 400; an invalid or expired token returns 401. See Errors for the full list.

Reference

• API reference — every list endpoint and its parameters.
• Transactions — the transactions endpoint used above.
• Orders — paginated and filterable order lists.

The exact parameter set varies by endpoint. When in doubt, confirm the supported pagination, sort, and filter parameters for a specific endpoint in the reference rather than assuming.