Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

This API executes a pre-built TikTok scraping Actor (Clockworks TikTok Scraper) and exposes two blocking (wait-for-completion) variants that return scraped data directly, plus a non-blocking variant that returns run metadata. Use the blocking variants when the caller expects immediate scraped results; use the non-blocking variant when the caller only needs a run id or run status without waiting for the scrape to finish.

How the domain is organized

Workflows revolve around three concepts: the Actor, a Run, and the Actor's outputs (Dataset items and the Key-value store). A single Run is one execution of the Actor. Runs may produce structured items in a Dataset and/or files/objects in the Actor Key-value store. The operations exposed correspond to two different use patterns:

  • Synchronous execution that waits for the run to finish and returns the Actor's output directly (either Dataset items or the Key-value store OUTPUT).
  • Synchronous execution that starts the run and returns metadata about the initiated Run (run id, status, timestamps) without returning dataset or key-value contents.

Every operation requires an Apify token and a body with the Actor input. Inspect the body type before calling to learn the exact field names the Actor expects (typical inputs include: a target identifier such as username/hashtag/URL, an item limit, proxy or request options, and other scraping controls). The API does not require constructing URLs or handling authentication headers—pass the token string and the typed body.

Entry points — which operation to call first

Pick the operation based on whether you need scraped data immediately or only run metadata.

  • If the user wants scraped items (JSON records) in one step, call run-sync-get-dataset-items-clockworks-tiktok-scraper. It runs the Actor, waits for completion, and returns the Dataset items produced by the run.

  • If the Actor stores results in the Key-value store (single JSON file, combined output, or artifacts) and the user needs that exact OUTPUT, call run-sync-clockworks-tiktok-scraper. It runs the Actor, waits for completion, and returns the Key-value store's OUTPUT value in the response body.

  • If the user only wants to start a run and receive run metadata (run id, status, timestamps) without waiting for the scrape to complete, call runs-sync-clockworks-tiktok-scraper. This returns the initiated Run information (useful when the caller intends to track progress externally or wants an immediate acknowledgement).

Always inspect the body input type for the chosen operation to determine the exact parameter names to supply (for example: whether the Actor expects username, hashtag, startUrls, maxItems, proxyConfig, etc.).

Common user requests and the operation to use

  • "Get the latest N posts from user X" — Use run-sync-get-dataset-items-clockworks-tiktok-scraper. Provide the fields that select the user and limit the item count. The response body will contain an array of items (or whatever structure the Actor emits to its Dataset).

  • "Download the actor OUTPUT (single JSON or file) for this scrape" — Use run-sync-clockworks-tiktok-scraper. That operation returns the Key-value store OUTPUT value (the Actor's single-file output) in the response body.

  • "Start a scheduled scrape and give me the run id" — Use runs-sync-clockworks-tiktok-scraper. The response body contains run metadata (including the run id) so the caller can refer to that run.

  • "Compare two runs or fetch data from a previously started run" — This API surface does not expose a separate fetch-by-run-id operation for retrieving dataset items or key-value contents after starting a run with runs-sync. To obtain data in one request, prefer the run-sync operations. If run metadata is required first, inform the user that runs-sync provides the run id but data retrieval is not returned by that call.

What the responses contain and how to interpret them

All operations return a status string and a body value. Expect these patterns:

  • run-sync-clockworks-tiktok-scraper: status indicates run outcome; body contains the Key-value store OUTPUT value the Actor wrote. The body shape depends on the Actor: it can be an object, a JSON array, or another serialized payload.

  • run-sync-get-dataset-items-clockworks-tiktok-scraper: status indicates run outcome; body contains the Dataset items emitted by the Actor. Typically this is an array of item objects, but confirm by inspecting the returned body.

  • runs-sync-clockworks-tiktok-scraper: status indicates initial request outcome (e.g., accepted/started); body contains a Runs response schema with run id, run status, timestamps, and other metadata. It does not include dataset items or Key-value store contents.

Because body is not strictly typed in the tooling you see here, always examine the returned body at runtime to determine where items or files appear and to shape the reply back to the user.

Non-obvious gotchas and practical tips

  • Choose the correct run-sync variant for the Actor's output location. The Actor may write results to the Dataset, to the Key-value store, or both. If the Actor writes only to the Key-value store and the dataset-focused operation is used, the dataset call will return empty. Conversely, if the Actor writes only dataset items and the key-value call is used, the key-value response will be empty or missing the expected OUTPUT.

  • runs-sync-clockworks-tiktok-scraper returns run metadata immediately and does not return scraped data. If the user expects scraped data in the response, do not use runs-sync; use one of the run-sync operations that wait for completion.

  • Synchronous runs wait for completion. If the scrape is large or the Actor takes a long time, the synchronous operation may take a while to return. When the caller explicitly wants an immediate acknowledgement or a run id to track later, prefer runs-sync.

  • The Actor's input schema determines how to request specific items (username vs hashtag vs URL). Before sending a call, inspect the operation's body type to find the exact field names the Actor expects. Typical fields to look for: a target identifier (username/hashtag/URL), a maximum items limit (limit/maxItems), and any proxy or request options.

  • Every call requires an Apify token string in the token parameter. Supply a valid token with appropriate permissions for running Actors and reading their outputs.

  • The status field in the response is the primary quick indicator of whether the run succeeded; examine body for the actual data or for error details the Actor may include.

Quick-call checklist

Before invoking an operation, run through this checklist:

  1. Decide whether you need data immediately or only run metadata.
  2. Choose the operation: dataset-returning (run-sync-get-dataset-items-*), key-value OUTPUT-returning (run-sync-clockworks-tiktok-scraper), or run-metadata (runs-sync-clockworks-tiktok-scraper).
  3. Inspect the chosen operation's body input type to learn exact field names and required fields.
  4. Provide a valid Apify token in token and populate the body accordingly.
  5. Call the operation and examine status and body. If status indicates success, return body (dataset items or OUTPUT) to the user; if using runs-sync, return the run id and metadata so the user can reference the run.

Following these patterns ensures the user gets the expected scraped data or run information without unnecessary extra runs or confusion about where the Actor writes its outputs.