# Get a whole account (/docs/recipes/get-a-whole-account) Walk every video, comment or follower an account has with a cursor loop that retries a failed page, stops on a cap and never pays twice for a page Send one handle, get back every video the account has, one page at a time, and stop on a cap you set. The same loop works on any list that returns a cursor, so the example also reads the comments of one video. You never skip a page, and you never pay twice for the one you already hold. Measured on 22/11/2026: a walk of 3 pages of one news publisher's TikTok videos read 30 videos for 3 credits. Reading the second page again straight after cost 0 credits. ## Start in five minutes Set your key once. Every block on this page reads it. ```bash title="Terminal" export SOCIALCRAWL_API_KEY=sc_your_key_here ``` Paste this prompt into your coding agent: ```text title="Prompt" Read https://www.socialcrawl.dev/docs/recipes/get-a-whole-account.md and follow it to list the TikTok videos of the handle washingtonpost. Use the key in SOCIALCRAWL_API_KEY. Price one page with dry_run=true first and show me the estimate. Then walk the pages with max_items=30 and max_credits=5, and never raise either number without asking me. ``` Or price the first page yourself. A dry run quotes it for 0 credits: ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/tiktok/profile/videos" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "handle=washingtonpost" \ --data-urlencode "dry_run=true" ``` On 22/11/2026 it answered `valid: true` and a hold of 1 credit for one page. ## How it works - Each answer holds one page of rows and a `next_cursor` that points at the next page. - You send that cursor back as `cursor`, exactly as you got it, and the walk moves on. - The walk ends when `has_more` is `false`. You never use `data.total` as the stop signal, because a list can leave it empty. - A page that fails with `429` or `503` is sent again with the same cursor, after the wait the answer asks for. - A cap such as `max_items` or `max_credits` keeps a long account from running up the bill. ## What you need | Call | What it gives | Credits | | --- | --- | --- | | `GET /v1/tiktok/profile/videos` | One page of an account's videos and the cursor for the next | Billed per page, see the [roster](/docs/endpoint-pricing.md) | | `GET /v1/tiktok/post/comments` | One page of a video's comments, the same cursor rule | Billed per page, see the [roster](/docs/endpoint-pricing.md) | | `GET /v1/utility/estimate` or `dry_run=true` | The price of a request or a capped walk | 0 | ## Steps ### Step 1: read one page and keep the cursor **cURL** ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/tiktok/profile/videos" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "handle=washingtonpost" ``` **Python** ```python title="Python" import json, os, urllib.parse, urllib.request url = "https://www.socialcrawl.dev/v1/tiktok/profile/videos?" + urllib.parse.urlencode({"handle": "washingtonpost"}) req = urllib.request.Request(url, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}) page = json.load(urllib.request.urlopen(req, timeout=120)) print(len(page["data"]["items"]), page["pagination"]["has_more"], page["pagination"]["next_cursor"][:24]) ``` - `pagination.next_cursor` is an opaque token. Do not decode it, trim it or build one. - On 22/11/2026 a page held 10 videos, `has_more` was `true` and the page cost 1 credit. ```json title="Response (trimmed)" { "data": { "items": [ { "post": { "id": "7681829627085507870" } } ] }, "credits_used": 1, "pagination": { "next_cursor": "sc.eyJ2Ijoy...", "has_more": true, "page_size": 10 } } ``` ### Step 2: send the cursor back until `has_more` is `false` Add `cursor=` to the same request and keep every other parameter the same. Stop when `pagination.has_more` is `false`. - A page can be empty and still bill. On 22/11/2026 a walk bounded by a date ended on an empty page with `has_more: false`, and that page cost 1 credit. - `data.total` is not the stop signal. On the video list it was `null`, and on the comment list it was a number the walk never needed. - Pages of one account run one after another, because each needs the cursor of the one before. ### Step 3: retry a failed page with the same cursor On `429` or `503`, wait for the `Retry-After` header and send the same URL again. Never advance past a page you did not read, and never restart from page 1. A failed page costs nothing, so the retry is free. The program at the bottom of the page does this for you. ### Step 4: cap the walk Send `max_items` and `max_credits` and the API walks the cursor for you in one call. A page starts only while its price still fits under `max_credits`. **cURL** ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/tiktok/profile/videos" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "handle=cnn" \ --data-urlencode "max_items=20" \ --data-urlencode "max_credits=2" ``` **Python** ```python title="Python" import json, os, urllib.parse, urllib.request query = {"handle": "cnn", "max_items": "20", "max_credits": "2"} url = "https://www.socialcrawl.dev/v1/tiktok/profile/videos?" + urllib.parse.urlencode(query) req = urllib.request.Request(url, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}) answer = json.load(urllib.request.urlopen(req, timeout=120)) print(len(answer["data"]["items"]), answer["data"]["walk"]["stopped"], answer["credits_used"]) ``` - `data.walk.stopped` says why the walk ended: `end`, `max_items`, `max_credits`, `max_pages` or `time_budget`. - `pagination.next_cursor` still resumes the walk right after the last row you received. - `GET /v1/utility/estimate` quotes the capped walk for free. On 22/11/2026 it said a request with `max_items=30` and `max_credits=5` charges up to 5 credits. - On 22/11/2026 the capped walk above returned 20 videos in 2 pages for 2 credits and stopped on `max_items`. ### Step 5: read a second list the same way Comments use the same cursor rule. Pass the video link from step 1. ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/tiktok/post/comments" \ -H "x-api-key: $SOCIALCRAWL_API_KEY" \ --data-urlencode "url=https://www.tiktok.com/@washingtonpost/video/7681829627085507870" \ --data-urlencode "max_items=30" \ --data-urlencode "max_credits=5" ``` On 22/11/2026 one page held 50 comments for 1 credit, and the walk stopped on `max_items` with `has_more` still `true`. ### Step 6: hand a long walk to a background job For many accounts, or a walk that outlasts one request, send the same call as an item of `POST /v1/prism/jobs`. The job resumes from its own cursor and keeps your limits. The [Async page](/docs/async.md#run-many-calls-to-one-get-as-a-job) has the body and how to read the result. ## Store only what is new Key each video on `post.id`. Save the last `next_cursor` you read next to your rows, so a walk that stopped on a cap carries on from there instead of from page 1. A row you already hold is not new, even when a later walk meets it again. To read only what was posted since your last run, use [Poll an account daily](/docs/recipes/poll-an-account-daily.md). ## What it costs Each page costs what one call to that endpoint costs, and a capped walk bills each page it reads. The [roster](/docs/endpoint-pricing.md) lists the price of every endpoint. What the runs measured on 22/11/2026: | Run | Rows | Credits | | --- | --- | --- | | The dry run of one page | 0 | 0 | | A walk of 3 pages by cursor | 30 videos | 3 | | The second page read again straight after | 10 videos | 0 (served from cache) | | A capped walk, `max_items=20` and `max_credits=2` | 20 videos | 2 | | One page of comments, `max_items=30` | 50 comments | 1 | | The full program below, capped at 3 pages | 30 videos | 3 | ## Tips, and what not to use - Do not walk with a guessed page number. The cursor is the only safe way to the next page. - Do not restart from page 1 after a failure. Send the same cursor again. - Do not read `data.total` as the stop signal. Read `has_more`. - A handle that returns no rows ends on the first page with `stopped: end` and costs 0 credits. - A page emptied by `since` or `until` is still billed. To pay only when something is new, use [Listening](/docs/engines/listening.md) or [Monitors](/docs/engines/monitors.md). - Within one account the pages run in order. To read many accounts at once, run them in parallel and keep the number of requests under your [rate limits](/docs/rate-limits.md). ## Full program and agent brief **Full program (Python)** ```python title="Python" # drain_account.py: read an account's videos page by page, each video kept once. # Run: SOCIALCRAWL_API_KEY=... python3 drain_account.py (Python 3.9+, nothing to install) import json import os import time import urllib.error import urllib.parse import urllib.request KEY = os.environ["SOCIALCRAWL_API_KEY"] BASE = "https://www.socialcrawl.dev/v1" PATH = "tiktok/profile/videos" PARAMS = {"handle": "washingtonpost"} MAX_PAGES = 3 # the cap: a surprise cost cannot run away def get(url): for attempt in range(6): req = urllib.request.Request(url, headers={"x-api-key": KEY}) try: with urllib.request.urlopen(req, timeout=120) as res: return json.load(res) except urllib.error.HTTPError as err: if err.code not in (429, 503) or attempt == 5: raise # Wait, then send the SAME url again: never move past a page you did not read. time.sleep(int(err.headers.get("Retry-After", "2"))) videos = {} cursor = None for page_number in range(1, MAX_PAGES + 1): query = dict(PARAMS) if cursor: query["cursor"] = cursor page = get(f"{BASE}/{PATH}?" + urllib.parse.urlencode(query)) for row in page["data"]["items"]: videos[row["post"]["id"]] = row cursor = page["pagination"]["next_cursor"] print(f"page {page_number}: {len(page['data']['items'])} rows, {page['credits_used']} credits, has_more={page['pagination']['has_more']}") if not page["pagination"]["has_more"]: cursor = None break print(f"{len(videos)} videos kept") if cursor: print("stopped at the cap; save this cursor to carry on later:", cursor[:24] + "...") ``` **Agent brief** ```text title="Agent brief" Goal: every video of one TikTok account, read page by page, each kept once, within a credit cap. Read https://www.socialcrawl.dev/docs/recipes/get-a-whole-account.md first. 1. Send GET /v1/tiktok/profile/videos with handle and dry_run=true. Show me the estimate. 2. Walk the pages: send pagination.next_cursor back as cursor, with every other parameter unchanged. 3. Stop when pagination.has_more is false, or when the cap of 3 pages is reached. Never use data.total. 4. On 429 or 503 wait for Retry-After and send the same cursor again. Never skip a page. 5. Store each video by post.id and save the last cursor. Do not raise the cap without asking me. ``` ## Next steps - [Poll an account daily](/docs/recipes/poll-an-account-daily.md): Fetch only the posts published since your last run. - [Pagination](/docs/pagination.md): The cursor rule, the walk report and every list that takes since. - [Comments in bulk](/docs/recipes/comments-in-bulk.md): Read the comments of many posts in one job.