How to paginate results

View as Markdown

Page through list results on GoDaddy APIs using markers, next links, returned cursors, and GraphQL connections.

Overview

GoDaddy APIs don't share one pagination scheme. Each list endpoint uses one of four patterns, and a few endpoints, like the Domains v2 lists, return everything in one response. This page shows how to page through results for each pattern. Go to the API reference for an endpoint's exact parameter names, defaults, and maximums.

Page sequentially. Parallel page-walks burn through your rate limit without finishing sooner.

Choose a pagination pattern

Find your endpoint's pattern in the following table, then go to that section. If your endpoint isn't listed, check its reference page for marker, pageToken, page, cursor, or after parameters:

PatternHow you can tellUsed by
MarkerThe response is a bare array, and you pass the last item back as marker.Domains v1 GET /v1/domains
Next linksThe response has items and links. A rel=next link means more results.Domains v3 domain names and DNS records, Hosting apps and deployments, Email, Customers, Commerce channels and transactions
Returned cursorThe response carries a cursor or token that you send on the next request.Shopping catalog search
GraphQL connectionsThe query returns edges and pageInfo.Commerce Catalog, Orders, and Taxes

Paginate with a marker

GET /v1/domains returns a bare array. Pass limit for the page size and marker for the last domain you received. The last page is the first response with fewer items than limit.

The following procedure retrieves every domain on the account.

  • Request pages until a response is shorter than limit:
# First page
curl -s "https://api.godaddy.com/v1/domains?limit=100" \
  -H "Authorization: Bearer $GODADDY_PAT"

# Next page: marker is the last domain from the previous page
curl -s "https://api.godaddy.com/v1/domains?limit=100&marker=$LAST_DOMAIN" \
  -H "Authorization: Bearer $GODADDY_PAT"

Go to List domains for the limit maximum and the full parameter list.

These endpoints return items plus a links array. Each link has a rel and an href. Request the first page, then follow rel=next until it's absent. The link carries the page token or page number for you, so you never build one yourself.

The following procedure retrieves every page of a list that returns links.

  • Request pages until the response has no rel=next link:
# First page
curl -s "https://api.godaddy.com/v3/domains/domain-names?pageSize=100" \
  -H "Authorization: Bearer $GODADDY_PAT"

# Next page: reuse the query string from the rel=next link
curl -s "https://api.godaddy.com/v3/domains/domain-names?$NEXT_QUERY" \
  -H "Authorization: Bearer $GODADDY_PAT"

The loop reuses only the query string from the link. Some APIs return the href as a full URL and others return a path without the API prefix, so rebuilding the request from your own base URL works for both. Replace base and the first-page query to page through a different endpoint.

Which parameter sits in the link depends on the endpoint. Some endpoints use pageToken and others use page. A few accept both, and an endpoint might reject a request that sends both. Go to the reference page for your endpoint for the details:

The Hosting logs endpoint also accepts pageSize, but it sets how many log lines come back, not a page size. Don't loop on it.

Send the returned cursor back

Some endpoints return a cursor in the response body. You send it on the next request, and the response flags the end of the results.

POST /v1/shopping/catalog/search takes pagination.limit and pagination.cursor in the request body. The response returns pagination.has_next_page and a pagination.cursor for the next page.

The following procedure retrieves every page of catalog search results.

  • Request pages until has_next_page is false:
# First page
curl -s -X POST "https://api.godaddy.com/v1/shopping/catalog/search" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Request-Id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "context": { "address_country": "US", "currency": "USD", "language": "en" },
    "pagination": { "limit": 20 }
  }'

# Next page: pass pagination.cursor from the previous response
curl -s -X POST "https://api.godaddy.com/v1/shopping/catalog/search" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Request-Id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "context": { "address_country": "US", "currency": "USD", "language": "en" },
    "pagination": { "limit": 20, "cursor": "'"$NEXT_CURSOR"'" }
  }'

Go to Search catalog for the Shopping parameters.

Paginate GraphQL queries

The Commerce Catalog, Orders, and Taxes GraphQL APIs return connections. A paginated query takes first and after, or last and before, and returns edges plus a pageInfo object. Pass pageInfo.endCursor as after to move forward. Stop when pageInfo.hasNextPage is false.

The following procedure retrieves every page of orders.

  • Request pages until hasNextPage is false:
# First page
curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -H "x-store-id: $STORE_ID" \
  -d '{"query": "query($after: ID) { orders(first: 10, after: $after) { edges { node { id number } } pageInfo { hasNextPage endCursor } } }"}'

# Next page: pass pageInfo.endCursor as the after variable
curl -s -X POST "https://api.godaddy.com/v1/commerce/order-subgraph" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -H "x-store-id: $STORE_ID" \
  -d '{"query": "query($after: ID) { orders(first: 10, after: $after) { edges { node { id number } } pageInfo { hasNextPage endCursor } } }", "variables": {"after": "'"$END_CURSOR"'"}}'

The after variable's type matches the schema. Orders cursors are ID, and Catalog and Taxes cursors are String. Catalog connections also expose totalCount. Catalog queries accept a paginationType argument that defaults to CURSOR.

  • Go to orders for the Orders arguments.
  • Go to skus for the Catalog arguments, including paginationType.
  • Go to rates for the Taxes arguments.

Common errors

The following table lists pagination errors and how to resolve each one.

StatusCauseAction
422The request sends both page and pageToken to an endpoint that accepts only one of them, like the Customers list.Send pageToken alone. Use the rel=next link instead of building the query yourself.
400A Hosting list request changes pageSize after the first page, or sends a page or other unknown parameter. A Hosting pageToken works only with the same pageSize as the request that returned it, and Hosting has no page parameter.Keep pageSize the same on every request. Use the rel=next link instead of building the query yourself.
429You paged too fast or in parallel.Page sequentially, and go to Handle rate limits for backoff.

Next

Agent & Automation Notes

PermissionsAny account
ScopesAny scope that allows list operations, for example domains.domain:read for GET /v3/domains/domain-names
Rate limitRate-limited per credential per window. Page sequentially rather than in parallel to stay within limits. Go to /docs/api-users/rate-limits for current values.
IdempotentYes
DestructiveNo
On failurePagination calls are read-only, so retrying a failed page request with the same parameters is safe. If a saved marker, token, or cursor is rejected, restart from the first page.

Last updated on

How is this guide?

On this page