Filtering & search

The items query accepts a filter argument (ItemFilterInput) plus a few sibling arguments for search, sorting, and saved views. This guide covers the most common patterns. For the full field list, see the ItemFilterInput reference.

Date ranges

Filter by when content was posted with takenAt, a date-range input with from and to bounds.

query.graphql

query ItemsFilterDateRange($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        takenAt
      }
    }
  }
}

variables.json

{
  "filter": {
    "takenAt": {
      "from": "2024-10-01T00:00:00Z",
      "to": "2024-12-31T00:00:00Z"
    }
  },
  "first": 20
}

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 ItemsFilterDateRange($filter: ItemFilterInput, $first: Int) {\n  items(filter: $filter, first: $first) {\n    totalCount\n    edges {\n      node {\n        id\n        caption\n        takenAt\n      }\n    }\n  }\n}",
  "variables": {
    "filter": {
      "takenAt": {
        "from": "2024-10-01T00:00:00Z",
        "to": "2024-12-31T00:00:00Z"
      }
    },
    "first": 20
  }
}'

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 ItemsFilterDateRange($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        takenAt
      }
    }
  }
}`,
    variables: {
      "filter": {
        "takenAt": {
          "from": "2024-10-01T00:00:00Z",
          "to": "2024-12-31T00:00:00Z"
        }
      },
      "first": 20
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query ItemsFilterDateRange($filter: ItemFilterInput, $first: Int) {
    items(filter: $filter, first: $first) {
      totalCount
      edges {
        node {
          id
          caption
          takenAt
        }
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "filter" => { "takenAt" => { "from" => "2024-10-01T00:00:00Z", "to" => "2024-12-31T00:00:00Z" } }, "first" => 20 } }.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 ItemsFilterDateRange($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        takenAt
      }
    }
  }
}
"""

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"filter": {"takenAt": {"from": "2024-10-01T00:00:00Z", "to": "2024-12-31T00:00:00Z"}}, "first": 20}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK 149 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"
          }
        },
        {
          "node": {
            "id": "3870b3f7-2066-56c1-b82e-f7c606c863fa",
            "caption": "Post #24 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-25T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "2adb5caf-5619-5fc5-b738-ba264cb394a7",
            "caption": "Short #23 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-24T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "5b570218-bf6a-5e05-9389-2f9bfe7f73ce",
            "caption": "Story #22 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-23T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "24bd35e7-4ae8-546b-bc76-b9cee5e1107f",
            "caption": "Reel #21 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-22T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "5503f877-fd11-5373-b372-ce4738980780",
            "caption": "Post #20 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-21T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "dbc66518-991e-5f66-9b93-f680af733f6e",
            "caption": "Short #19 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-20T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "ec78fe4c-a457-5446-b77b-b739e526253e",
            "caption": "Story #18 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-19T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "28aa71e5-7d0a-5edc-b11d-545f28ad32e7",
            "caption": "Reel #17 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-18T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "eef04e09-52e4-5eae-8b7a-b07b87e35c1a",
            "caption": "Post #16 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-17T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "259f36f6-b92b-55ff-b065-40906bfc2826",
            "caption": "Short #15 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-16T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "9d3b36d5-f71d-5283-abf9-6f3a1415ac9c",
            "caption": "Story #14 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-15T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "1ee18054-a7dc-5951-9711-58b254138bae",
            "caption": "Reel #13 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-14T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "be093358-c18b-5a9b-af8d-7e39d2b1e39c",
            "caption": "Post #12 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-13T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "f81eb89a-9d29-5f25-9d73-4f0e32bb5cab",
            "caption": "Short #11 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-12T00:00:00Z"
          }
        },
        {
          "node": {
            "id": "de3d94b7-2a6e-5b6d-b726-9e4c38279a61",
            "caption": "Story #10 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-11T00:00:00Z"
          }
        }
      ]
    }
  }
}

Engagement ranges

engagement filters on metric ranges — likes, views, comments, and more — each expressed as a minimum, a maximum, or both. Related fields such as followersCount and viralityScore narrow by audience size and virality.

query.graphql

query ItemsFilterEngagementRange($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        currentEngagement {
          likes
          views
        }
      }
    }
  }
}

variables.json

{
  "filter": {
    "engagement": [
      {
        "field": "LIKE_COUNT",
        "range": {
          "from": 100
        }
      }
    ]
  },
  "first": 20
}

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 ItemsFilterEngagementRange($filter: ItemFilterInput, $first: Int) {\n  items(filter: $filter, first: $first) {\n    totalCount\n    edges {\n      node {\n        id\n        caption\n        currentEngagement {\n          likes\n          views\n        }\n      }\n    }\n  }\n}",
  "variables": {
    "filter": {
      "engagement": [
        {
          "field": "LIKE_COUNT",
          "range": {
            "from": 100
          }
        }
      ]
    },
    "first": 20
  }
}'

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 ItemsFilterEngagementRange($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        currentEngagement {
          likes
          views
        }
      }
    }
  }
}`,
    variables: {
      "filter": {
        "engagement": [
          {
            "field": "LIKE_COUNT",
            "range": {
              "from": 100
            }
          }
        ]
      },
      "first": 20
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query ItemsFilterEngagementRange($filter: ItemFilterInput, $first: Int) {
    items(filter: $filter, first: $first) {
      totalCount
      edges {
        node {
          id
          caption
          currentEngagement {
            likes
            views
          }
        }
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "filter" => { "engagement" => [{ "field" => "LIKE_COUNT", "range" => { "from" => 100 } }] }, "first" => 20 } }.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 ItemsFilterEngagementRange($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        currentEngagement {
          likes
          views
        }
      }
    }
  }
}
"""

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

200 OK 209 lines

{
  "data": {
    "items": {
      "totalCount": 30,
      "edges": [
        {
          "node": {
            "id": "452a119f-393e-5edf-a7f7-f563294f3885",
            "caption": "Reel #29 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "390",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "d8a538a5-8857-5c0c-b3fb-a2b83c8d2a0b",
            "caption": "Post #28 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "380",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "330cce49-6139-5672-9c61-33fb35bc73e2",
            "caption": "Short #27 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "370",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "a61d036b-fe79-538c-bbbb-1f97162cab3c",
            "caption": "Story #26 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "360",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "de1860a7-2d98-5eda-8977-116583725c74",
            "caption": "Reel #25 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "350",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "3870b3f7-2066-56c1-b82e-f7c606c863fa",
            "caption": "Post #24 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "340",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "2adb5caf-5619-5fc5-b738-ba264cb394a7",
            "caption": "Short #23 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "330",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "5b570218-bf6a-5e05-9389-2f9bfe7f73ce",
            "caption": "Story #22 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "320",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "24bd35e7-4ae8-546b-bc76-b9cee5e1107f",
            "caption": "Reel #21 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "310",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "5503f877-fd11-5373-b372-ce4738980780",
            "caption": "Post #20 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "300",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "dbc66518-991e-5f66-9b93-f680af733f6e",
            "caption": "Short #19 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "290",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "ec78fe4c-a457-5446-b77b-b739e526253e",
            "caption": "Story #18 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "280",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "28aa71e5-7d0a-5edc-b11d-545f28ad32e7",
            "caption": "Reel #17 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "270",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "eef04e09-52e4-5eae-8b7a-b07b87e35c1a",
            "caption": "Post #16 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "260",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "259f36f6-b92b-55ff-b065-40906bfc2826",
            "caption": "Short #15 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "250",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "9d3b36d5-f71d-5283-abf9-6f3a1415ac9c",
            "caption": "Story #14 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "240",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "1ee18054-a7dc-5951-9711-58b254138bae",
            "caption": "Reel #13 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "230",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "be093358-c18b-5a9b-af8d-7e39d2b1e39c",
            "caption": "Post #12 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "220",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "f81eb89a-9d29-5f25-9d73-4f0e32bb5cab",
            "caption": "Short #11 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "210",
              "views": "0"
            }
          }
        },
        {
          "node": {
            "id": "de3d94b7-2a6e-5b6d-b726-9e4c38279a61",
            "caption": "Story #10 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "likes": "200",
              "views": "0"
            }
          }
        }
      ]
    }
  }
}

Super-search

superSearch runs semantic and fuzzy search over content. It supports three modes:

EMBEDDING_CONTENT — semantic and visual similarity.
FUZZY_CAPTION — fuzzy match against captions.
FUZZY_TRANSCRIPTION — fuzzy match against spoken-word transcriptions.

Depending on the mode, you provide a searchQuery, an imageUrl, a similarMediaContentId, or a fileName. See the FilterSuperSearchMode reference for the full input.

query.graphql

query ItemsSuperSearch($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
      }
    }
  }
}

variables.json

{
  "filter": {
    "superSearch": {
      "mode": "FUZZY_CAPTION",
      "searchQuery": "Northwind Botanicals"
    }
  },
  "first": 20
}

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 ItemsSuperSearch($filter: ItemFilterInput, $first: Int) {\n  items(filter: $filter, first: $first) {\n    totalCount\n    edges {\n      node {\n        id\n        caption\n      }\n    }\n  }\n}",
  "variables": {
    "filter": {
      "superSearch": {
        "mode": "FUZZY_CAPTION",
        "searchQuery": "Northwind Botanicals"
      }
    },
    "first": 20
  }
}'

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 ItemsSuperSearch($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
      }
    }
  }
}`,
    variables: {
      "filter": {
        "superSearch": {
          "mode": "FUZZY_CAPTION",
          "searchQuery": "Northwind Botanicals"
        }
      },
      "first": 20
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query ItemsSuperSearch($filter: ItemFilterInput, $first: Int) {
    items(filter: $filter, first: $first) {
      totalCount
      edges {
        node {
          id
          caption
        }
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "filter" => { "superSearch" => { "mode" => "FUZZY_CAPTION", "searchQuery" => "Northwind Botanicals" } }, "first" => 20 } }.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 ItemsSuperSearch($filter: ItemFilterInput, $first: Int) {
  items(filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
      }
    }
  }
}
"""

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

200 OK 129 lines

{
  "data": {
    "items": {
      "totalCount": 30,
      "edges": [
        {
          "node": {
            "id": "0ea0f5a3-257d-580f-ba63-9b693166eecd",
            "caption": "Reel #9 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "1ee18054-a7dc-5951-9711-58b254138bae",
            "caption": "Reel #13 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "24bd35e7-4ae8-546b-bc76-b9cee5e1107f",
            "caption": "Reel #21 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "259f36f6-b92b-55ff-b065-40906bfc2826",
            "caption": "Short #15 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "28aa71e5-7d0a-5edc-b11d-545f28ad32e7",
            "caption": "Reel #17 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "2adb5caf-5619-5fc5-b738-ba264cb394a7",
            "caption": "Short #23 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "330cce49-6139-5672-9c61-33fb35bc73e2",
            "caption": "Short #27 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "3870b3f7-2066-56c1-b82e-f7c606c863fa",
            "caption": "Post #24 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "4083ca4a-13e4-54d1-a116-ba4af73cc59b",
            "caption": "Story #6 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "452a119f-393e-5edf-a7f7-f563294f3885",
            "caption": "Reel #29 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "5503f877-fd11-5373-b372-ce4738980780",
            "caption": "Post #20 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "5b570218-bf6a-5e05-9389-2f9bfe7f73ce",
            "caption": "Story #22 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
            "caption": "Post #0 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "76a4c7a9-6abd-5392-9869-83b006c9c4a6",
            "caption": "Short #7 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "7f0da362-a674-5057-95ca-4df2380e63e3",
            "caption": "Post #8 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "80ca1b0c-5fc2-583e-acbc-6a3e02e05e9e",
            "caption": "Reel #5 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "852bb4df-4e3c-519e-9318-7a950148e349",
            "caption": "Post #4 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "99bb982f-563c-5cd7-9475-2798be58f881",
            "caption": "Reel #1 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "9d3b36d5-f71d-5283-abf9-6f3a1415ac9c",
            "caption": "Story #14 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        },
        {
          "node": {
            "id": "a61d036b-fe79-538c-bbbb-1f97162cab3c",
            "caption": "Story #26 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals"
          }
        }
      ]
    }
  }
}

Content type and platform

provider narrows by platform (INSTAGRAM, TIKTOK, YOUTUBE, INTERNAL). itemTypes narrows by content type, using the FilterItemType enum: POST, REEL, STORY, TIKTOK, TIKTOK_STORY, YOUTUBE, YOUTUBE_SHORT.

Custom-attribute conditions

Custom attributes are not filtered through ItemFilterInput. They use a separate top-level argument, customAttributeConditions, a sibling of filter on the items query. Each condition has the shape { field, operator, type, value }.

query.graphql

query ItemsCustomAttributeCondition($customAttributeConditions: [CustomAttributeConditionInput!], $first: Int) {
  items(customAttributeConditions: $customAttributeConditions, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        customAttributes
      }
    }
  }
}

variables.json

{
  "customAttributeConditions": [
    {
      "field": "sentiment",
      "operator": "IS",
      "type": "SINGLE_SELECT_V2",
      "value": "positive"
    }
  ],
  "first": 20
}

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 ItemsCustomAttributeCondition($customAttributeConditions: [CustomAttributeConditionInput!], $first: Int) {\n  items(customAttributeConditions: $customAttributeConditions, first: $first) {\n    totalCount\n    edges {\n      node {\n        id\n        caption\n        customAttributes\n      }\n    }\n  }\n}",
  "variables": {
    "customAttributeConditions": [
      {
        "field": "sentiment",
        "operator": "IS",
        "type": "SINGLE_SELECT_V2",
        "value": "positive"
      }
    ],
    "first": 20
  }
}'

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 ItemsCustomAttributeCondition($customAttributeConditions: [CustomAttributeConditionInput!], $first: Int) {
  items(customAttributeConditions: $customAttributeConditions, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        customAttributes
      }
    }
  }
}`,
    variables: {
      "customAttributeConditions": [
        {
          "field": "sentiment",
          "operator": "IS",
          "type": "SINGLE_SELECT_V2",
          "value": "positive"
        }
      ],
      "first": 20
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query ItemsCustomAttributeCondition($customAttributeConditions: [CustomAttributeConditionInput!], $first: Int) {
    items(customAttributeConditions: $customAttributeConditions, first: $first) {
      totalCount
      edges {
        node {
          id
          caption
          customAttributes
        }
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "customAttributeConditions" => [{ "field" => "sentiment", "operator" => "IS", "type" => "SINGLE_SELECT_V2", "value" => "positive" }], "first" => 20 } }.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 ItemsCustomAttributeCondition($customAttributeConditions: [CustomAttributeConditionInput!], $first: Int) {
  items(customAttributeConditions: $customAttributeConditions, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        customAttributes
      }
    }
  }
}
"""

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"customAttributeConditions": [{"field": "sentiment", "operator": "IS", "type": "SINGLE_SELECT_V2", "value": "positive"}], "first": 20}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK 63 lines

{
  "data": {
    "items": {
      "totalCount": 5,
      "edges": [
        {
          "node": {
            "id": "852bb4df-4e3c-519e-9318-7a950148e349",
            "caption": "Post #4 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "customAttributes": {
              "sentiment": "positive"
            }
          }
        },
        {
          "node": {
            "id": "e1bf0fd2-53cc-536d-9168-35635aa64fd8",
            "caption": "Short #3 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "customAttributes": {
              "sentiment": "positive"
            }
          }
        },
        {
          "node": {
            "id": "a78ec1f9-5c4b-5c8a-b3b1-e028e575b606",
            "caption": "Story #2 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "customAttributes": {
              "sentiment": "positive",
              "collections": [
                "34714af3-fb12-5d72-8094-c94ce02be1fa"
              ]
            }
          }
        },
        {
          "node": {
            "id": "99bb982f-563c-5cd7-9475-2798be58f881",
            "caption": "Reel #1 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "customAttributes": {
              "sentiment": "positive",
              "collections": [
                "34714af3-fb12-5d72-8094-c94ce02be1fa"
              ]
            }
          }
        },
        {
          "node": {
            "id": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
            "caption": "Post #0 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "customAttributes": {
              "sentiment": "positive",
              "collections": [
                "34714af3-fb12-5d72-8094-c94ce02be1fa"
              ]
            }
          }
        }
      ]
    }
  }
}

Operators

Conditions use the FilterOperator enum:

BETWEEN, CONTAINS, CONTAINS_ALL, DOES_NOT_CONTAIN, ENDS_WITH, EQUAL, IS, IS_EMPTY, IS_NOT, IS_NOT_EMPTY, IS_RELATIVE_TO_TODAY, LESS_THAN, LESS_THAN_OR_EQUAL, MORE_THAN, MORE_THAN_OR_EQUAL, NOT_EQUAL, STARTS_WITH.

See the FilterOperator reference for details.

Sorting

Order results with the sorting argument. The default is TAKEN_AT descending, newest content first. Other keys are listed in the ItemSortKey reference.

query.graphql

query ItemsSorting($sorting: [ItemSortingInput!], $first: Int) {
  items(sorting: $sorting, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        currentEngagement {
          earnedMediaValue
        }
      }
    }
  }
}

variables.json

{
  "sorting": [
    {
      "sortKey": "EARNED_MEDIA_VALUE",
      "sortOrder": "DESC"
    }
  ],
  "first": 20
}

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 ItemsSorting($sorting: [ItemSortingInput!], $first: Int) {\n  items(sorting: $sorting, first: $first) {\n    totalCount\n    edges {\n      node {\n        id\n        caption\n        currentEngagement {\n          earnedMediaValue\n        }\n      }\n    }\n  }\n}",
  "variables": {
    "sorting": [
      {
        "sortKey": "EARNED_MEDIA_VALUE",
        "sortOrder": "DESC"
      }
    ],
    "first": 20
  }
}'

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 ItemsSorting($sorting: [ItemSortingInput!], $first: Int) {
  items(sorting: $sorting, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        currentEngagement {
          earnedMediaValue
        }
      }
    }
  }
}`,
    variables: {
      "sorting": [
        {
          "sortKey": "EARNED_MEDIA_VALUE",
          "sortOrder": "DESC"
        }
      ],
      "first": 20
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query ItemsSorting($sorting: [ItemSortingInput!], $first: Int) {
    items(sorting: $sorting, first: $first) {
      totalCount
      edges {
        node {
          id
          caption
          currentEngagement {
            earnedMediaValue
          }
        }
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "sorting" => [{ "sortKey" => "EARNED_MEDIA_VALUE", "sortOrder" => "DESC" }], "first" => 20 } }.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 ItemsSorting($sorting: [ItemSortingInput!], $first: Int) {
  items(sorting: $sorting, first: $first) {
    totalCount
    edges {
      node {
        id
        caption
        currentEngagement {
          earnedMediaValue
        }
      }
    }
  }
}
"""

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

200 OK 189 lines

{
  "data": {
    "items": {
      "totalCount": 30,
      "edges": [
        {
          "node": {
            "id": "452a119f-393e-5edf-a7f7-f563294f3885",
            "caption": "Reel #29 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "780"
            }
          }
        },
        {
          "node": {
            "id": "d8a538a5-8857-5c0c-b3fb-a2b83c8d2a0b",
            "caption": "Post #28 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "760"
            }
          }
        },
        {
          "node": {
            "id": "330cce49-6139-5672-9c61-33fb35bc73e2",
            "caption": "Short #27 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "740"
            }
          }
        },
        {
          "node": {
            "id": "a61d036b-fe79-538c-bbbb-1f97162cab3c",
            "caption": "Story #26 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "720"
            }
          }
        },
        {
          "node": {
            "id": "de1860a7-2d98-5eda-8977-116583725c74",
            "caption": "Reel #25 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "700"
            }
          }
        },
        {
          "node": {
            "id": "3870b3f7-2066-56c1-b82e-f7c606c863fa",
            "caption": "Post #24 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "680"
            }
          }
        },
        {
          "node": {
            "id": "2adb5caf-5619-5fc5-b738-ba264cb394a7",
            "caption": "Short #23 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "660"
            }
          }
        },
        {
          "node": {
            "id": "5b570218-bf6a-5e05-9389-2f9bfe7f73ce",
            "caption": "Story #22 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "640"
            }
          }
        },
        {
          "node": {
            "id": "24bd35e7-4ae8-546b-bc76-b9cee5e1107f",
            "caption": "Reel #21 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "620"
            }
          }
        },
        {
          "node": {
            "id": "5503f877-fd11-5373-b372-ce4738980780",
            "caption": "Post #20 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "600"
            }
          }
        },
        {
          "node": {
            "id": "dbc66518-991e-5f66-9b93-f680af733f6e",
            "caption": "Short #19 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "580"
            }
          }
        },
        {
          "node": {
            "id": "ec78fe4c-a457-5446-b77b-b739e526253e",
            "caption": "Story #18 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "560"
            }
          }
        },
        {
          "node": {
            "id": "28aa71e5-7d0a-5edc-b11d-545f28ad32e7",
            "caption": "Reel #17 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "540"
            }
          }
        },
        {
          "node": {
            "id": "eef04e09-52e4-5eae-8b7a-b07b87e35c1a",
            "caption": "Post #16 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "520"
            }
          }
        },
        {
          "node": {
            "id": "259f36f6-b92b-55ff-b065-40906bfc2826",
            "caption": "Short #15 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "500"
            }
          }
        },
        {
          "node": {
            "id": "9d3b36d5-f71d-5283-abf9-6f3a1415ac9c",
            "caption": "Story #14 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "480"
            }
          }
        },
        {
          "node": {
            "id": "1ee18054-a7dc-5951-9711-58b254138bae",
            "caption": "Reel #13 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "460"
            }
          }
        },
        {
          "node": {
            "id": "be093358-c18b-5a9b-af8d-7e39d2b1e39c",
            "caption": "Post #12 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "440"
            }
          }
        },
        {
          "node": {
            "id": "f81eb89a-9d29-5f25-9d73-4f0e32bb5cab",
            "caption": "Short #11 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "420"
            }
          }
        },
        {
          "node": {
            "id": "de3d94b7-2a6e-5b6d-b726-9e4c38279a61",
            "caption": "Story #10 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "currentEngagement": {
              "earnedMediaValue": "400"
            }
          }
        }
      ]
    }
  }
}

Saved views

Pass presetId to drive the query from a saved view. When you supply presetId to items, the filter, sorting, and customAttributeConditions arguments are ignored; the saved view defines the query entirely.

A preset that is unknown, belongs to another workspace, or is the wrong type for items returns a GraphQL error with extensions.code = "WRONG_VIEW_TYPE_FOR_ITEMS". The error lists the accessors the items query does accept in extensions.allowedAccessors.

200 OK 24 lines

{
  "errors": [
    {
      "message": "Preset \"00000000-0000-0000-0000-000000000000\" was not found in the current workspace.",
      "extensions": {
        "code": "WRONG_VIEW_TYPE_FOR_ITEMS",
        "allowedAccessors": [
          "media_deck",
          "collections"
        ]
      },
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "items"
      ]
    }
  ],
  "data": null
}

For the full error model, see the Errors guide.