Skip to content
truescrape
Free key

Contents

Site

Quickstart

Ten minutes, four steps

The fourth step is the one that matters. The first three are the same as any HTTP API.

  1. 01

    Get a key

    Sign in to get your free key. A first sign-in creates your team and a starter key. The raw key appears exactly once and is stored as a SHA-256 hash, so copy it then; a lost key is rotated, never recovered.

  2. 02

    Make a call

    Every endpoint is a GET with your key in the x-api-key header. Responses are JSON in a fixed envelope.

  3. 03

    Read the accounting

    Headers on every response tell you what the call cost and whether it was served from cache, with no separate usage endpoint needed to find out.

  4. 04

    Stop polling

    Once you are checking the same targets repeatedly, subscribe instead. We run the checks at the normal price and call your webhook only when the data moves.

1. Get a key

  1. 01

    Open API keys in the dashboard.

  2. 02

    Under Create a key, name it after where it will run (production, staging, a teammate’s laptop) and press Create key.

  3. 03

    The raw key is printed once, right there, with a copy button. Copy it before you leave the page. Only its SHA-256 is stored, so the list afterwards shows a prefix and never the key. A key you did not save is replaced, not recovered.

Give each environment its own key so revoking one never takes the others down with it. The daily spend cap is a separate, team-wide control on the billing page. It bounds what the whole team can spend in a day, so it is a backstop against a runaway loop rather than a per-key budget.

Prefer to try it before wiring anything up? The dashboard playground mints a key of its own on first use, so you can send a real request without creating or pasting anything.

2. Make a call

first request
export API="${API:-https://api.truescrape.com}"
export KEY="sk_live_..."

curl "$API/v1/youtube/channel?handle=@mkbhd" \
  -H "x-api-key: $KEY"

3. Read the accounting

Every response carries what it cost, what is left, and whether it came from cache. You never have to make a second call to find out what the first one did.

response headers
HTTP/1.1 200 OK
x-request-id: req_01JB8Z3M6QW2K9
x-credits-charged: 1
x-credits-remaining: 998
x-cache: MISS
x-response-time: 412ms

Adding cache_max_age is the single highest-leverage change you can make to a bill. It says how stale a copy you will accept; anything older is fetched live.

cached request
# Say how stale a copy you will accept.
# A hit costs nothing and never touches the platform.
curl "$API/v1/youtube/channel?handle=@mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"

# x-cache: HIT
# x-credits-charged: 0

The same call from code

TypeScript
const response = await fetch(
  `${API}/v1/youtube/transcript?url=8XkPqR2nLvE&cache_max_age=7d`,
  { headers: { 'x-api-key': KEY } },
);

const body = await response.json();

if (!body.success) {
  // Failures are never charged. Retry the retryable ones.
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.text);          // the whole transcript
console.log(body.meta.creditsCharged); // 0 on a cache hit
Python
import os, httpx

API = os.environ["API"]
KEY = os.environ["KEY"]

r = httpx.get(
    f"{API}/v1/youtube/transcript",
    params={"url": "8XkPqR2nLvE", "cache_max_age": "7d"},
    headers={"x-api-key": KEY},
    timeout=30,
)
body = r.json()

if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"]["text"])

4. Stop polling

This is the step people skip, and it is the one that deletes the most code. If you are checking the same creator every hour to see whether they posted, subscribe once: we run the checks at the endpoint’s normal price, compare the content, and tell you only when something changed.

watch a target
curl -X POST "$API/v1/subscriptions" \
  -H "x-api-key: $KEY" \
  -H "content-type: application/json" \
  -d '{
    "endpoint": "youtube.channel",
    "params": { "handle": "@mkbhd" },
    "webhook_url": "https://you.example/hooks/social"
  }'

Deliveries are signed and retried with backoff. If your endpoint stays down the delivery is eventually given up on, so treat a webhook as a notification rather than the record. The watch can be read back over the API either way. Jobs, batches & webhooks covers the delivery semantics in full.

Try it in the playgroundBrowse every endpoint