StatusSupportGet API keyDashboard
Using the APIPagination

Using the API

Pagination

Use with AI

How list endpoints return items in pages, how to fetch the next page with a cursor, and how pages are priced.

List endpoints return their items a page at a time, and every one of them pages the same way, so you write the loop once.

The response

A successful list response has three keys: data, an array of items in the resource's shared schema; page, which says whether more items exist and how to get them; and meta, as on every response:

Shape of a list response
{
  "data": [
    "…"
  ],
  "page": {
    "has_more": true,
    "next_cursor": "…",
    "next_cursor_expires_at": "…",
    "end_reason": "…"
  },
  "meta": {
    "request_id": "…",
    "platform": "…",
    "source": "…",
    "is_cached": true,
    "credits_charged": 0,
    "latency_ms": 0,
    "fetched_at": "…",
    "input": {},
    "credits_remaining": 0,
    "client_request_id": "…",
    "warnings": []
  }
}
200 OK (TikTok Posts API)
{
  "data": [
    {
      "approximate_fields": [
        "metrics.view_count",
        "metrics.like_count",
        "metrics.share_count"
      ],
      "author": {
        "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
        "display_name": "Khabane lame",
        "id": "127905465618821121",
        "is_verified": true,
        "url": "https://www.tiktok.com/@khaby.lame",
        "username": "khaby.lame"
      },
      "coauthors": [],
      "duration_ms": 9000,
      "hashtags": [
        "learnfromkhaby",
        "comedy"
      ],
      "id": "7697307919943060767",
      "is_nsfw": null,
      "is_pinned": null,
      "is_sponsored": null,
      "language": "en",
      "media": [
        {
          "alt_text": null,
          "duration_ms": 9000,
          "expires_at": null,
          "height": 1280,
          "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oQbHQmFfa5VY3NlkEGDAQT00RzqAqBOETlEafj~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
          "type": "video",
          "url": null,
          "width": 720
        }
      ],
      "mentions": [],
      "metrics": {
        "comment_count": 7503,
        "like_count": 305900,
        "quote_count": null,
        "repost_count": null,
        "save_count": 16282,
        "share_count": 32600,
        "view_count": 4600000
      },
      "platform": "tiktok",
      "platform_specific": {
        "tiktok": {
          "author_follower_count": null,
          "author_sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
          "board": null,
          "country_code": null,
          "is_ad": false,
          "is_ai_generated": true,
          "location": null,
          "music": {
            "author_name": "Khabane lame",
            "cover_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
            "duration_ms": 9000,
            "id": "7697308007327730462",
            "is_original": true,
            "play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast8/tos-useast8-v-27dcd7-tx2/oEEIAbfkyMVIeCnAjGGKYI9gqpqTImLAAfYo09/?a=1988&bti=ODszNWYuMDE6&&bt=125&ft=GcAInInz7Th~v-RGXq8Zmo&mime_type=audio_mpeg&rc=M2lybXI5cnE4ZTMzaTU8NEBpM2lybXI5cnE4ZTMzaTU8NEBxYG5tMmRrNjZhLS1kMTJzYSNxYG5t…",
            "title": "original sound"
          }
        }
      },
      "platform_type": "video",
      "published_at": "2026-10-16T16:46:21Z",
      "text": "I guess is time to retire #learnfromkhaby #comedy 🥊",
      "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oQbHQmFfa5VY3NlkEGDAQT00RzqAqBOETlEafj~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
      "title": null,
      "type": "video",
      "unknown_fields": [],
      "url": "https://www.tiktok.com/@khaby.lame/video/7697307919943060767"
    },
    {
      "approximate_fields": [
        "metrics.view_count",
        "metrics.like_count",
        "metrics.comment_count"
      ],
      "author": {
        "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
        "display_name": "Khabane lame",
        "id": "127905465618821121",
        "is_verified": true,
        "url": "https://www.tiktok.com/@khaby.lame",
        "username": "khaby.lame"
      },
      "coauthors": [],
      "duration_ms": 30000,
      "hashtags": [
        "learnfromkhaby",
        "comedy"
      ],
      "id": "7694335322922044703",
      "is_nsfw": null,
      "is_pinned": null,
      "is_sponsored": null,
      "language": "en",
      "media": [
        {
          "alt_text": null,
          "duration_ms": 30000,
          "expires_at": null,
          "height": 1280,
          "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/osAHzWAIipBAxVMie5CIDqxK0ArEREAAEKVSfn~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
          "type": "video",
          "url": null,
          "width": 720
        }
      ],
      "mentions": [],
      "metrics": {
        "comment_count": 12600,
        "like_count": 690100,
        "quote_count": null,
        "repost_count": null,
        "save_count": 40145,
        "share_count": 20800,
        "view_count": 6900000
      },
      "platform": "tiktok",
      "platform_specific": {
        "tiktok": {
          "author_follower_count": null,
          "author_sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
          "board": null,
          "country_code": null,
          "is_ad": false,
          "is_ai_generated": true,
          "location": null,
          "music": {
            "author_name": "Khabane lame",
            "cover_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
            "duration_ms": 30000,
            "id": "7694335437137087262",
            "is_original": true,
            "play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast8/tos-useast8-v-27dcd7-tx2/o4fHr3qIArT5AEXEiCLVExDGAeqCAIOVe4joPR/?a=1988&bti=ODszNWYuMDE6&&bt=125&ft=GcAInInz7Th~v-RGXq8Zmo&mime_type=audio_mpeg&rc=M3lzeG45cm92ZTMzaTU8NEBpM3lzeG45cm92ZTMzaTU8NEBzNGtiMmRjXjBhLS1kMTJzYSNzNGti…",
            "title": "original sound"
          }
        }
      },
      "platform_type": "video",
      "published_at": "2026-10-08T16:31:16Z",
      "text": "Was the ball out, or was it just my imagination? 🤨#learnfromkhaby #comedy",
      "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/osAHzWAIipBAxVMie5CIDqxK0ArEREAAEKVSfn~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
      "title": null,
      "type": "video",
      "unknown_fields": [],
      "url": "https://www.tiktok.com/@khaby.lame/video/7694335322922044703"
    },
    {
      "approximate_fields": [
        "metrics.view_count",
        "metrics.like_count",
        "metrics.share_count"
      ],
      "author": {
        "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
        "display_name": "Khabane lame",
        "id": "127905465618821121",
        "is_verified": true,
        "url": "https://www.tiktok.com/@khaby.lame",
        "username": "khaby.lame"
      },
      "coauthors": [],
      "duration_ms": 34000,
      "hashtags": [
        "learnfromkhaby",
        "comedy"
      ],
      "id": "7691740195418377502",
      "is_nsfw": null,
      "is_pinned": null,
      "is_sponsored": null,
      "language": "en",
      "media": [
        {
          "alt_text": null,
          "duration_ms": 34000,
          "expires_at": null,
          "height": 1280,
          "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o0jRDQRMAbfFAlZX8eqGQcARBqerRfAHR7gVSU~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
          "type": "video",
          "url": null,
          "width": 720
        }
      ],
      "mentions": [],
      "metrics": {
        "comment_count": 7325,
        "like_count": 418500,
        "quote_count": null,
        "repost_count": null,
        "save_count": 20087,
        "share_count": 23900,
        "view_count": 5000000
      },
      "platform": "tiktok",
      "platform_specific": {
        "tiktok": {
          "author_follower_count": null,
          "author_sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
          "board": null,
          "country_code": null,
          "is_ad": false,
          "is_ai_generated": true,
          "location": null,
          "music": {
            "author_name": "Khabane lame",
            "cover_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
            "duration_ms": 34000,
            "id": "7691740326570019615",
            "is_original": true,
            "play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast8/tos-useast8-v-27dcd7-tx2/ogcDFBGWoU0A8F0eIAAREf8XVjvDqICFsEDJAo/?a=1988&bti=ODszNWYuMDE6&&bt=125&ft=GcAInInz7Th~v-RGXq8Zmo&mime_type=audio_mpeg&rc=M3hmanQ5cjg7ZDMzaTU8NEBpM3hmanQ5cjg7ZDMzaTU8NEBjMGgyMmRzbnNhLS1kMTJzYSNjMGgy…",
            "title": "original sound"
          }
        }
      },
      "platform_type": "video",
      "published_at": "2026-10-01T16:40:54Z",
      "text": "Just give me 5 more minutes 😭#learnfromkhaby #comedy",
      "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o0jRDQRMAbfFAlZX8eqGQcARBqerRfAHR7gVSU~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
      "title": null,
      "type": "video",
      "unknown_fields": [],
      "url": "https://www.tiktok.com/@khaby.lame/video/7691740195418377502"
    }
  ],
  "page": {
    "has_more": true,
    "next_cursor": "c1.EXAMPLE_CURSOR",
    "next_cursor_expires_at": "2026-10-26T12:00:00Z",
    "end_reason": null
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "tiktok",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 888,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": {
      "kind": "profile",
      "id": "127905465618821121",
      "url": "https://www.tiktok.com/@khaby.lame"
    },
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}

Long arrays and strings are shortened for display.

FieldTypeDescription
page.has_morebooleanTrue when another page exists; then next_cursor is set. An empty page with has_more true is not the end.
page.next_cursorstring or nullPass as cursor, with the same other parameters, to get the next page; null at the end.
page.next_cursor_expires_atstring (date-time) or nullWhen next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.
page.end_reasonstring or nullWhy there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.
One of end, platform_limit, max_pages

There are no totals: platforms don't report them reliably, and counting would cost extra requests.

Parameters

Every list endpoint accepts these on top of its own parameters and the common options:

ParameterTypeDescription
limitinteger
min 1		Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.
cursorstringpage.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.

Getting the next page

  1. Send the first request without cursor.
  2. If page.has_more is true, send the same request again with cursor set to page.next_cursor from the previous response.
  3. Stop when page.has_more is false.
JavaScript
const items = [];
let cursor = null;
do {
  const params = new URLSearchParams({ ...yourParams, ...(cursor ? { cursor: cursor } : {}) });
  const res = await fetch(`https://socialtap.dev/v1/<platform>/<endpoint>?${params}`, {
    headers: { "x-api-key": process.env.SOCIALTAP_API_KEY },
  });
  if (!res.ok) throw new Error((await res.json()).error.code);
  const body = await res.json();
  items.push(...body.data);
  cursor = body.page.next_cursor;
} while (cursor);

Keep every other parameter the same: only limit and the common options such as max_age may change between pages.

Every list page with a next page also carries the next request ready to send, in the standard link header (rel="next"): your request with the cursor filled in. Generic HTTP clients can follow it.

Why a list ended

When page.has_more is false, page.end_reason says why, so fewer items than you expected is never a mystery:

  • end: the list really ended, or it reached the time window you asked for with since/until.
  • platform_limit: the platform stops serving further pages although the list goes on (many platforms cap how far logged-out visitors can scroll). Repeating the walk later will not get further.
  • max_pages: the walk reached SocialTap's cap on pages per list.

Time windows

List endpoints ordered by time accept since (inclusive) and until (exclusive), as an RFC 3339 time or a date (see Requests). On a newest-first list, paging stops as soon as an item older than since appears: the last page has page.has_more false with page.end_reason end, and the older pages are neither fetched nor charged. until filters out newer items; the pages that hold them are still read, so they are charged.

Cursors

Cursors are opaque and short-lived: don't parse, build or store them. Each one stops working at page.next_cursor_expires_at. A cursor that is malformed, expired, from another endpoint, or sent with different parameters fails with invalid_cursor (HTTP 400) and costs nothing; repeat the original request without a cursor to start again.

Order and page size

Each list endpoint states the order of its items and its page size: the default and the largest limit it accepts (larger values are reduced). One request reads one page from the platform, so a list of N items takes about N ÷ page size requests when you leave limit out.

EndpointOrderPage sizeCursor lifetimePrice per page
Amazon Deals APIAmazon's Today's Deals order (its own ranking, as the grid shows it)up to 1001 hour1 credit
Amazon Offers APIThe buy box offer first, then every other offer in Amazon's order: by price plus delivery, lowest firstup to 1124 hours1 credit
Amazon Reviews APIAmazon's top reviews: the marketplace's own first, then other countries'up to 2024 hours1 credit
Amazon Product Search APIAmazon's Featured order, sponsored results among themup to 6024 hours1 credit
Amazon Shop Lists APIthe storefront's order: the list created or changed most recently first, with the lists the influencer pinned at the top of the first pageup to 2024 hours1 credit
Amazon Shop Posts APIthe storefront's: newest first within each tab, after the posts the influencer pinned; type=all lists the videos, then the photosup to 2024 hours1 credit
Amazon Best Sellers APIAmazon's rank in the list (1 = top)up to 5024 hours1 credit
Apple Music Album Search APIApple Music's own relevance order for the queryup to 5024 hours1 credit
Apple Music Artist Search APIApple Music's own relevance order for the queryup to 5024 hours1 credit
Apple Music Playlist Search APIApple Music's own relevance order for the queryup to 5024 hours1 credit
Apple Music Track Search APIApple Music's own relevance order for the queryup to 5024 hours1 credit
Apple Music Top Albums APIApple Music's own chart order (1 = most played)up to 5024 hours1 credit
Apple Music Top Playlists APIApple Music's own chart order (1 = most played)up to 5024 hours1 credit
Apple Music Top Tracks APIApple Music's own chart order (1 = most played)up to 10024 hours1 credit
Bluesky Comments APIMost liked first, the replies Bluesky folds under "Show more replies" lastup to 1,00024 hours1 credit
Bluesky User Posts APImost recent activity first: a post by when it was posted, a repost by when it was repostedup to 10024 hours1 credit
Bluesky Post Search APInewest first, by the time each post states, to the secondup to 10024 hours1 credit
Facebook Ad Library Advertiser Ads APImost impressions firstup to 101 hour1 credit
Facebook Comments APIFacebook's All comments view: every top-level comment, the most relevant firstup to 1024 hours1 credit
Facebook Page Events APIoldest firstup to 824 hours1 credit
Facebook Group Posts APIFacebook's New posts: newest first by when a post entered the group's feedup to 31 hour1 credit
Facebook Profile Photos APINewest first, as the Photos tab shows themup to 81 hour1 credit
Facebook City Events APIFacebook's ranking of the city's events, not by dateup to 123 hours1 credit
Facebook Profile Posts APInewest firstup to 31 hour1 credit
Facebook Reels APInewest firstup to 101 hour1 credit
Facebook Comment Replies APIoldest firstup to 1024 hours1 credit
Facebook Ad Library Search APImost impressions firstup to 101 hour1 credit
Facebook Ad Library Advertiser Search APIthe search box's own orderup to 1524 hours1 credit
Facebook Event Search APIFacebook's ranking of the results, not by dateup to 2030 minutes1 credit
Facebook Group Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Facebook Marketplace Search APIMarketplace's Suggested orderup to 303 hours1 credit
Facebook Marketplace Location Search APImost relevant first, as Marketplace's location picker ranks themup to 1024 hours1 credit
Facebook Post Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Facebook Page and People Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Google Ads Transparency Center Advertiser Ads APIlast shown, most recent firstup to 4024 hours1 credit
Google Ads Transparency Center Ads by Website APIlast shown, most recent firstup to 4024 hours1 credit
Google Ads Transparency Center Advertiser Search APIGoogle's order, as the center's search box lists the matchesup to 10024 hours1 credit
Google Ads Transparency Center Search Suggestions APIthe center's search box order: on each page its advertisers, then its websitesup to 2024 hours1 credit
Instagram Comments APInewest firstup to 2424 hours1 credit
Instagram Hashtag Posts APIInstagram's ranking of the hashtag's reels (its public results page's order)up to 2424 hours1 credit
Instagram Highlights APIthe order of the account's highlights tray on its profileup to 1024 hours1 credit
Instagram Location Posts APInewest firstup to 1824 hours1 credit
Instagram Highlight Stories APIoldest firstup to 5024 hours1 credit
Instagram Posts APInewest firstup to 1224 hours1 credit
Instagram Reels APInewest firstup to 1224 hours1 credit
Instagram Hashtag Search APIInstagram's search ranking (most relevant first)up to 5524 hours1 credit
Instagram Location Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Instagram Search APIInstagram's ranking for the keyword (its popular page's order)up to 2424 hours1 credit
Instagram User Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Instagram Audio Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Instagram Search Suggestions APIthe exact account first, then Instagram's tag search rankingup to 5624 hours1 credit
Instagram Similar Accounts APIInstagram's suggestion orderup to 5024 hours1 credit
Instagram Audio Reels APIInstagram's ranking of the audio's reels (the order its audio page shows)up to 1224 hours1 credit
Instagram Trending Reels APIInstagram's reels feed order (a fresh selection on each first page)up to 4024 hours1 credit
Kwai User Posts APInewest firstup to 5024 hours1 credit
LinkedIn Ad Library Search APImost recently started firstup to 2424 hours1 credit
LinkedIn Post Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
LinkedIn Company and People Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Pinterest Board Pins APIPinterest's order for logged-out visitors: mostly the latest saved first, with a few pins it picks moved to the topup to 5024 hours1 credit
Pinterest Boards APIthe order the account's profile shows its boards in: its own arrangement (A to Z, or one it set by hand), else the boards saved to most recently firstup to 5024 hours1 credit
Pinterest Profile Pins APInewest firstup to 2524 hours1 credit
Pinterest Search APIPinterest's own relevance order for the queryup to 2524 hours1 credit
Pinterest Trends APIPinterest Trends' rank for the board (1 = top)up to 5024 hours1 credit
Reddit Comments APIReddit's own order for the post (Best, or the order its moderators suggest), each comment followed by the replies Reddit showsup to 20024 hours1 credit
Reddit User Posts APInewest firstup to 2524 hours1 credit
Reddit User Comments APInewest firstup to 2524 hours1 credit
Reddit Comment Search APIReddit's search ranking (best match)up to 1024 hours1 credit
Reddit Search APIReddit's relevance order (its search ranking)up to 71 hour1 credit
Reddit User Search APIReddit's relevance orderup to 724 hours1 credit
Reddit Subreddit Search APIReddit's relevance orderup to 101 hour1 credit
Reddit Subreddit Posts APIReddit's Best order (its default ranking of a subreddit's posts)up to 251 hour1 credit
Rumble Comments APInewest firstup to 50024 hours1 credit
Rumble Channel Videos APIRumble's upload order (newest uploads first, not strictly by published_at)up to 251 hour1 credit
Rumble Search APIRumble's relevance orderup to 361 hour1 credit
Snapchat Comments APISnapchat's own ranking of the Spotlight's comments; a comment's replies oldest firstup to 2624 hours1 credit
SoundCloud Artist Tracks APInewest firstup to 5024 hours1 credit
Spotify Playlist Tracks APIthe playlist's own order, as its owner or Spotify arranged itup to 10024 hours1 credit
Spotify Podcast Episodes APIthe show's own order: newest first, or from the first episode on a show meant to be heard in orderup to 5024 hours1 credit
Spotify Album Search APISpotify's own ranking for the queryup to 10024 hours1 credit
Spotify Artist Search APISpotify's own ranking for the queryup to 10024 hours1 credit
Spotify Playlist Search APISpotify's own ranking for the queryup to 10024 hours1 credit
Spotify Podcast Search APISpotify's own ranking for the queryup to 10024 hours1 credit
Spotify Track Search APISpotify's own ranking for the queryup to 10024 hours1 credit
Telegram Channel Posts APInewest firstup to 2024 hours1 credit
Telegram Channel Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
Threads Comments APInewest firstup to 5030 minutes1 credit
Threads Posts APInewest firstup to 2524 hours1 credit
Threads Search APIThreads' best matches (its search ranking)up to 2024 hours1 credit
Threads User Search APIThreads' search rankingup to 10024 hours1 credit
TikTok Comments APITikTok's comment ranking (the order its app shows)up to 5024 hours1 credit
TikTok Effect Posts APITikTok's ranking of the effect's posts (the order its effect page shows)up to 3024 hours1 credit
TikTok Followers APInewest follower first (most recently followed)up to 3024 hours1 credit
TikTok Following APImost recently followed firstup to 3024 hours1 credit
TikTok Hashtag Posts APITikTok's ranking of the hashtag's top posts (the order its embed shows)up to 1024 hours1 credit
TikTok Liked Posts APImost recent like first (when the account liked each post)up to 3024 hours1 credit
TikTok Place Posts APITikTok's ranking of the place's posts (the order its place page shows)up to 3024 hours1 credit
TikTok Playlist Posts APIthe playlist's own order (its owner's for a playlist, the order TikTok shows a collection's posts in)up to 3024 hours1 credit
TikTok Playlists APIthe account's playlists in the order it set, then its public collectionsup to 3024 hours1 credit
TikTok Posts APInewest firstup to 1524 hours1 credit
TikTok Comment Replies APITikTok's reply order (the order its app shows: a reply to a reply follows the one it answers)up to 5024 hours1 credit
TikTok Ad Library Search APIrelevance (keywords) or newestup to 1224 hours1 credit
TikTok Hashtag Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
TikTok Search APITikTok's relevance order for the keywordup to 301 hour1 credit
TikTok User Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
TikTok Sound Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
TikTok Search Suggestions APITikTok's search box order (most likely search first)up to 2024 hours1 credit
TikTok Top Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
TikTok Sound Posts APITikTok's ranking of the sound's posts (the order its sound page shows)up to 3024 hours1 credit
TikTok Top Ads APICreative Center's rank by rank_by, best firstup to 2024 hours1 credit
TikTok Top Videos APICreative Center's rank by the rank_by metric (1 = top)up to 2024 hours1 credit
TikTok Trending Hashtags APICreative Center's trend rank (1 = most popular)up to 2024 hours1 credit
TikTok Trending Videos APITikTok's explore feed orderup to 3024 hours1 credit
TikTok Shop Store Products APITikTok Shop's store order: best-selling first (units sold, most first)up to 201 hour1 credit
TikTok Shop Reviews APITikTok Shop's recommended order (the order its product page shows reviews in)up to 524 hours1 credit
TikTok Shop Search APITikTok Shop's relevance orderup to 301 hour1 credit
Truth Social Posts APInewest firstup to 2024 hours1 credit
Twitch Schedule APISoonest first, a week per pageup to 5024 hours1 credit
Twitch Videos APInewest firstup to 1001 hour1 credit
X (Twitter) Community Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
X (Twitter) Hashtag Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit
X (Twitter) Post Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
X (Twitter) User Search APIthe search engine's ranking (most relevant first)up to 5024 hours1 credit + 1 per result filled in
YouTube Comments APInewest firstup to 201 hour1 credit
YouTube Channel Videos APInewest firstup to 481 hour1 credit

Pricing

A list endpoint's price is per page: every successful page costs the same, however many items it holds and whatever limit you send. A smaller limit lowers neither the price of a page nor the cost of a walk (it takes more pages, below). Empty pages are charged like any other successful page. Failed requests, including invalid_cursor, are free, and so are pages served from the cache. See Credits and caching.

A smaller limit costs more

A limit below the page size does not split one charge into parts. The request returns the first limit items of a platform page, and the next request, with its cursor, serves the rest of that same platform page: it is fetched again and charged as a page each time. Walking a page in parts therefore costs one page per part, and because the platform page is read again for every part, items can shift between those requests if the platform adds or removes items in the meantime, so an item may repeat or be skipped.

Omitting limit is the cheapest way to walk a list: every request returns a full page, and each platform page is read and charged once. Use a smaller limit only when you need fewer items than a page holds and will stop there.

Errors

On top of the errors every endpoint can return, list endpoints have these:

CodeHTTPRetryMeaningWhat to do
invalid_cursor400NoThe cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it.Repeat the original request without cursor to start the list again.

A rejected cursor costs nothing; repeat the original request without cursor to start again.

Last updated