Batches & automations

n8n, Make and Zapier

Each call is one HTTP step. Set it up like this in any tool:

• Method and URL: POST https://api.cleanscript.ai/v1/transcript, or /v1/extract for fields.
• Header: Authorization with the value Bearer <key>. Store it as a credential, not in the step.
• Body (JSON): {"url": "<the post link>"}, plus prompt, preset or schema for fields.
• Timeout: 2 minutes or more. Short posts answer in seconds; long videos take longer.
• Next steps: map text (transcript) or data (fields) from the response.

In n8n, use the HTTP Request node with a Header Auth credential and Send Body as JSON; set the timeout under Options. In Make, use HTTP, Make a request, with Parse response on. In Zapier, use Webhooks by Zapier, Custom Request.

If a step gives up before the answer arrives, run it again: asking again for the same thing within 6 hours is free, and a request that fails is never charged.

Many posts from code

Your account allows a number of requests a minute (rate_limit_per_minute in GET /v1/account). Run a few requests at a time; the SDKs wait and retry when you hit the limit (429) or a temporary error (503), and send an Idempotency-Key so a retry is never charged twice.

from concurrent.futures import ThreadPoolExecutor
from cleanscript_ai import CleanScript, CleanScriptError

client = CleanScript(max_retries=4)

def run(url):
    try:
        return url, client.transcript(url).text
    except CleanScriptError as error:
        return url, error  # error.code says why: video_unavailable, no_captions…

with ThreadPoolExecutor(max_workers=4) as pool:
    for url, result in pool.map(run, urls):
        print(url, result)

Handle failures by code

• Retry later: rate_limited, source_unavailable, processing_failed (the SDKs retry these for you; over HTTP, wait for Retry-After) and timeout (retry once; the result is often ready by then).
• Skip and record: video_unavailable, no_captions, video_too_long, language_unavailable, invalid_url, unsupported_platform. Retrying won't change the answer.
• Stop the batch: insufficient_credits (top up, then resume) and unauthorized (check the key).

Over HTTP, send an Idempotency-Key header unique to the post, such as transcript- plus the post ID (1 to 128 letters, digits, ., _, : or -), and reuse it when you retry that post: within 6 hours a retry returns the first successful result instead of running again. Retrying a request that failed, with the same key, runs it again.

Before a large batch

Check your balance with GET /v1/account (free). Every response also carries X-Credits-Used and X-Credits-Remaining. A 10-minute video costs 1 credit for its transcript, or 3 credits with fields; see Credits & limits for the rates.