Pagination

Paginated fields return a Relay-style connection. You request a page with first and after, and read pageInfo to know whether — and how — to fetch the next one. Every connection in the API shares this shape, so the field tables are documented once in the Pagination reference; this guide is the how-to.

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 for the records directly, or edges when you need each node’s cursor. If you want the size of the full result set, request totalCount.

Page-size bounds

first defaults to 20 and must be between 1 and 100 — except engagementHistory, which accepts up to 1000 so a single item’s full snapshot history can be pulled in one page. A value outside the range is rejected with a GraphQL validation error — it is not silently clamped, so a request for first: 500 fails rather than quietly returning 100.

Lists that are not connections

A handful of 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.

They are not unbounded. Each returns at most 1000 rows, and the cap is silent: you get the first 1000 in the field’s own order, with no error and no signal that more exist.

The capped fields are collections, contentViews, creatorViews, socialProfileViews, viewGroups, customAttributeSchemas, and filterPresets. Each field’s own 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 OK48 lines · expand

{
  "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