Pagination

Every list endpoint in the Hydra API uses cursor-based pagination. This approach scales to any dataset size and produces stable results even as new records are created between pages.

How it works

Each list request returns a pagination object alongside the data array:

{
	"data": [...],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi0wOC0yNCIsImlkIjoicHJvZF9hYmMxMjMifQ==",
		"has_more": true,
		"total": 142
	}
}

Field	Type	Description
cursor	string | null	Opaque token to fetch the next page. null on the last page.
has_more	boolean	Whether more results exist beyond this page.
total	integer	Total count of records matching the query filters.

To fetch the next page, pass the cursor value as a query parameter:

curl "https://api.hydrajs.dev/v1/products?cursor=eyJ0IjoiMjAyNi..." \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Page size

Use the limit parameter to control how many records are returned per page. The default is 25, and the maximum is 250.

# Fetch 100 products per page
curl "https://api.hydrajs.dev/v1/products?limit=100" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Sorting

Most list endpoints support sort and order parameters:

# Newest first (default)
curl "https://api.hydrajs.dev/v1/products?sort=created_at&order=desc"

# Alphabetical by title
curl "https://api.hydrajs.dev/v1/products?sort=title&order=asc"

Available sort fields vary by resource — check the endpoint reference for each.

Iterating all pages

To process every record, loop until has_more is false:

const hydra = new Hydra({ secret_key: 'sk_live_...' });

// Option 1: async iterator (recommended)
for await (const product of hydra.products.iterate({ limit: 100 })) {
	console.log(product.title);
}

// Option 2: collect everything into an array
const all = await hydra.products.toArray({ limit: 100 });

Without the SDK, implement the loop manually:

let cursor: string | undefined;

do {
	const params = new URLSearchParams({ limit: '100' });
	if (cursor) params.set('cursor', cursor);

	const res = await fetch(`https://api.hydrajs.dev/v1/products?${params}`, {
		headers: { Authorization: `Bearer ${SECRET_KEY}` },
	});
	const { data, pagination } = await res.json();

	for (const product of data) {
		// process each product
	}

	cursor = pagination.has_more ? pagination.cursor : undefined;
} while (cursor);

Sparse fieldsets

Use the fields parameter to limit which fields are returned. This reduces payload size when you only need a few properties:

curl "https://api.hydrajs.dev/v1/products?fields=id,title,handle,status" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

The id field is always included regardless of the fields parameter. Unknown field names are silently ignored.

Expanding related data

Use the expand parameter to inline related resources in the response, avoiding extra API calls:

curl "https://api.hydrajs.dev/v1/products?expand=variants,images" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Available expansions vary by resource. Check the endpoint reference for the list of supported values.