Pagination

Paginated fields return a Relay-style connection. You request a page with first and after, and read pageInfo to know whether to fetch the next one. Every connection in the API shares this shape. This guide covers how to page through results; for the connection field tables, see the Pagination reference.

The cursor loop

Pass first to set the page size. Read pageInfo.hasNextPage to decide whether to continue, and pass pageInfo.endCursor as the next request’s after value. Repeat until hasNextPage is false.

Select nodes to get the records directly, or edges when you need each node’s cursor. To get the size of the full result set, request totalCount.

Page-size bounds

first defaults to 20 and must be between 1 and 100. The exception is engagementHistory, which accepts up to 1000 so you can fetch a single item’s full snapshot history in one page. Values outside the range are rejected with a GraphQL validation error rather than clamped: a request for first: 500 fails instead of returning 100 results.

Lists that are not connections

A few fields return a plain list rather than a cursor connection, because the result set is naturally small: a workspace’s saved views, its Collections, its custom-attribute schemas. They take no first and no after.

These lists are capped at 1000 rows. When a result is truncated, you get the first 1000 rows in the field’s own order, with no error and no other indication that more rows exist.

The capped fields are collections, contentViews, creatorViews, socialProfileViews, viewGroups, customAttributeSchemas, and filterPresets. Each field’s reference page states the cap.

Walkthrough

Paginate items page by page

Fetch page one, then page two using the returned endCursor.

Step 1

query.graphql

query ItemsPaginationPage1($first: Int) {
  items(first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        takenAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

variables.json

{
  "first": 5
}

Headers

Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a

Request · cURL

curl https://app.archive.com/api/v2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer docs_demo_token_0000000000000000000000' \
  -H 'WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a' \
  -d '{
  "query": "query ItemsPaginationPage1($first: Int) {\n  items(first: $first) {\n    totalCount\n    edges {\n      node {\n        id\n        caption\n        takenAt\n      }\n    }\n    pageInfo {\n      hasNextPage\n      endCursor\n    }\n  }\n}",
  "variables": {
    "first": 5
  }
}'

Request · Node.js

const response = await fetch("https://app.archive.com/api/v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer docs_demo_token_0000000000000000000000",
    "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
  },
  body: JSON.stringify({
    query: `query ItemsPaginationPage1($first: Int) {
  items(first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        takenAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}`,
    variables: {
      "first": 5
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query ItemsPaginationPage1($first: Int) {
    items(first: $first) {
      totalCount
      edges {
        node {
          id
          caption
          takenAt
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "first" => 5 } }.to_json,
  "Content-Type" => "application/json",
  "Authorization" => "Bearer docs_demo_token_0000000000000000000000",
  "WORKSPACE-ID" => "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
)
puts response.body

Request · Python

import json
import requests

query = """
query ItemsPaginationPage1($first: Int) {
  items(first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        takenAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
"""

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"first": 5}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK 48 lines

{
  "data": {
    "items": {
      "totalCount": 30,
      "edges": [
        {
          "node": {
            "id": "452a119f-393e-5edf-a7f7-f563294f3885",
            "caption": "Reel #29 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-30T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "d8a538a5-8857-5c0c-b3fb-a2b83c8d2a0b",
            "caption": "Post #28 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-29T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "330cce49-6139-5672-9c61-33fb35bc73e2",
            "caption": "Short #27 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-28T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "a61d036b-fe79-538c-bbbb-1f97162cab3c",
            "caption": "Story #26 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-27T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "de1860a7-2d98-5eda-8977-116583725c74",
            "caption": "Reel #25 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-26T00:00:00Z"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "Z2lkOi8vYXJjaGl2ZS9JdGVtL2RlMTg2MGE3LTJkOTgtNWVkYS04OTc3LTExNjU4MzcyNWM3NA=="
      }
    }
  }
}

Step 2