Reference · v1

TikTok Archives API

Programmatic access to profiles, regions, video, slideshow and audio downloads, stories and lives, with real-time chat and video plus automatic alerts when a user goes live.

Are you an AI or a script? The full reference is available as Markdown, no need to parse this page: /api.md (also /llms.txt).

Base URLhttps://geometryamerica.xyz/api/v1
Get an API key See methods
23methods
100requests / day
10keys per account
SSEreal time

Your dashboard

Manage your API keys and check today's usage and your live alerts.

Loading…

Quick start

Three steps to make your first request.

01

Create your account

It's the same account as the website. If you already have one, log in.

02

Generate a key

From your dashboard. You can have up to 10, for example one per project.

03

Make the request

Send the key in the Authorization header and call any method.

curl "https://geometryamerica.xyz/api/v1/getProfileInfo?username=tiktok" \
  -H "Authorization: Bearer TU_API_KEY"

Authentication

All requests to /api/v1/ require an API key. It can be sent in three ways:

Header (recommended)
Authorization: Bearer ga_…
Alternative header
X-API-Key: ga_…
Parameter
?key=ga_… — for EventSource (chat) and video players, which can't send headers.
Treat your key like a password. Don't put it in a public website's code or in repositories. If it leaks, revoke it from your dashboard and create a new one; your other keys keep working.

Limits and quota

The limit is per account: all your keys share the same 100 daily requests.

Requests
100 per day per account. Resets at 00:00 UTC.
What counts
Only successful responses (2xx). Errors don't use quota.
Chat and stream
getLiveChat and getLiveBuffer count 1 on connect and 1 more per hour open. Without quota the connection is closed.
Open connections
Up to 3 at once per account (chat, stream, liveEvents and clips from downloadLive).
Keys
Up to 10 active per account.
Live alerts
Up to 10 callbacks per account; callback alerts don't use quota. With liveEvents connecting is free and each delivered alert counts as 1.
Downloads
Links returned by downloadTT are valid for 6 hours and don't use quota.

Every response includes your usage in the usage field and in these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-10-05T00:00:00Z

Errors

JSON responses always have the same shape. On error, ok is false and error.code identifies the cause.

{
  "ok": false,
  "error": { "code": "not_live", "message": "@usuario no está en directo ahora mismo." },
  "usage": { "used": 13, "limit": 100, "remaining": 87, "resetsAt": "2026-10-05T00:00:00Z" }
}
HTTPcodeMeaning
400bad_requestA parameter is missing or invalid.
401missing_key · invalid_keyNo key was sent, or it's wrong or revoked.
404not_found · not_liveThe resource doesn't exist, or the user isn't live.
409limit_reached · duplicateCallback limit reached, or the callback already exists.
410expired_linkThe download link expired; call again downloadTT.
429daily_limit · too_many_streamsDaily quota used up, or 3 connections already open.
502upstream_errorTikTok didn't respond. Retry in a few seconds.
503busyThe server has too many lives open at once.

Methods

They all return JSON, except the ones that return files or streams.

Alert format

When a user watched with liveCallback starts or ends a live, a POST with JSON is sent to your URL. Checks run every minute. liveEvents delivers this same body over SSE. ongoing is true when the live was already running when you started watching the user.

Event live_start

{
  "event": "live_start",
  "username": "usuario",
  "roomId": "7312345678901234567",
  "title": "En vivo",
  "cover": "https://…/cover.jpeg",
  "startedAt": "2026-10-04T18:02:11Z",
  "url": "https://www.tiktok.com/@usuario/live",
  "watchUrl": "https://geometryamerica.xyz/live/usuario",
  "ongoing": false,
  "callbackId": 4,
  "sentAt": "2026-10-04T18:02:40Z"
}

Event live_end

{
  "event": "live_end",
  "username": "usuario",
  "roomId": "7312345678901234567",
  "title": "En vivo",
  "startedAt": "2026-10-04T18:02:11Z",
  "endedAt": "2026-10-04T19:40:03Z",
  "durationSeconds": 5872,
  "url": "https://www.tiktok.com/@usuario/live",
  "callbackId": 4,
  "sentAt": "2026-10-04T19:41:10Z"
}
Discord webhooks. If the URL is https://discord.com/api/webhooks/…, the alert is sent as a Discord message with the live's cover, no coding needed.

Verifying the signature

Every alert includes X-GA-Signature: sha256=…, an HMAC-SHA256 of the body using the secret you got when creating the callback.

// Node.js (Express)
const crypto = require('crypto');
app.post('/aviso', express.raw({ type: '*/*' }), (req, res) => {
  const esperado = 'sha256=' + crypto
    .createHmac('sha256', process.env.GA_SECRET)
    .update(req.body).digest('hex');
  if (req.get('X-GA-Signature') !== esperado)
    return res.sendStatus(401);
  const ev = JSON.parse(req.body);
  console.log(ev.event, ev.username);
  res.sendStatus(200);
});
# Python (Flask)
import hmac, hashlib, os
from flask import Flask, request

app = Flask(__name__)

@app.post("/aviso")
def aviso():
    firma = "sha256=" + hmac.new(
        os.environ["GA_SECRET"].encode(),
        request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(firma, request.headers.get("X-GA-Signature", "")):
        return "", 401
    ev = request.get_json()
    print(ev["event"], ev["username"])
    return "", 200

Your server must reply 2xx within 8 seconds. After 20 consecutive failures the callback is paused; you can re-enable it with “Try it” from your dashboard.

ESEN