How to paginate results
View as MarkdownPage 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:
| Pattern | How you can tell | Used by |
|---|---|---|
| Marker | The response is a bare array, and you pass the last item back as marker. | Domains v1 GET /v1/domains |
| Next links | The 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 cursor | The response carries a cursor or token that you send on the next request. | Shopping catalog search |
| GraphQL connections | The 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.
Follow next links
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=nextlink:
# 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:
- Go to List domain names for the
pageTokenparameters. - Go to List DNS records for the
pageandtotalRequiredparameters. - Go to List apps and List deployments for Hosting. Other Hosting lists, like subscriptions and domains, return a single page.
- Go to List mailboxes for Email.
- Go to List customers for Customers.
- Go to Get channels and Get transactions for Commerce.
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_pageis 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
hasNextPageis 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.
| Status | Cause | Action |
|---|---|---|
422 | The 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. |
400 | A 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. |
429 | You paged too fast or in parallel. | Page sequentially, and go to Handle rate limits for backoff. |
Next
- Go to List registered domains for a complete paginated example with filters.
- Go to Handle rate limits for retry and backoff guidance.
Agent & Automation Notes
Any scope that allows list operations, for example domains.domain:read for GET /v3/domains/domain-namesRelated
Last updated on
How is this guide?