API overview

The trackagoat API is a REST API over HTTPS. Authenticate with a Bearer API key, send and receive JSON, and every response has the same shape: { data, error, meta }. Every plan includes API access: Free allows 200 requests a day, Starter 1,000 and Ultra 50,000, with a per-key limit of 60 a minute. See Plans and limits for the live numbers.

Base URL: https://www.trackagoat.com/api/v2

Machine-readable spec#

This is the one place these locations are documented; other pages link here.

• OpenAPI spec: GET /api/v2/openapi.json. Import it into Postman, Insomnia or any OpenAPI-compatible tool, or generate a client from it.
• Data model: GET /api/v2/schema. Entities, fields and relationships. See OpenAPI and schema.
• MCP server: https://www.trackagoat.com/api/mcp, for Claude and other MCP clients. See MCP server.
• Changelog: GET /api/v2/changelog. Every changelog entry as JSON, newest first. No API key needed. See Changelog API.
• These docs as Markdown: /llms.txt, or append .md to any docs URL. See llms.txt and raw docs.

The multi-platform model#

Trackagoat 2.0 is multi-platform. A creator is a person or brand, and an account is one of their presences on a platform (tiktok or instagram; the platform enum also accepts youtube, reserved for YouTube tracking, which isn't available yet). A creator owns one or more accounts, and videos hang off accounts.

• Creators embed their accounts[] array and expose a derived top-level handle (the primary account's handle: TikTok first, else earliest-created).
• Tracking configuration (tracking_mode, start/end dates, the handle) lives on the account, not the creator.
• Plan limits count accounts: the thing that gets scraped: not creators.

See the Creators and accounts guide for the full concept.

Authentication#

See Authentication for how to generate and use API keys.

Response envelope#

Every endpoint returns JSON with this shape:

{
  "data": <payload or null>,
  "error": <error string or null>,
  "meta": <pagination info or null>
}

Successful responses have data set and error: null. Error responses have data: null and error set to a message string.

Pagination#

List endpoints use cursor-based pagination:

GET /api/v2/creators?limit=50&cursor=<value>

The meta object on list responses:

{
  "hasMore": true,
  "nextCursor": "2026-03-15T10:00:00Z"
}

Keep fetching until meta.hasMore is false.

Date ranges#

Analytics and stats endpoints accept ?from=YYYY-MM-DD&to=YYYY-MM-DD. Both default to the last 30 days if omitted.

GET /api/v2/analytics?entity=creator&entity_id=<uuid>&metric=views&from=2026-01-01&to=2026-03-31

API key scopes#

Keys carry explicit permission scopes set at creation time:

Write endpoints reject keys that only have read scope with 403 insufficient_scope.

A key acts on behalf of one member: the person who created it, or the member an org admin picked under Acts as. It can never do more than that member can in the app. Its scopes are a ceiling, checked against the member's current org role on every request: if they are demoted from org admin the key loses admin and admin-only actions (403 insufficient_role), and if they leave or are removed from the org the key stops working (401 key_member_removed). A key made for someone else also stops working if the admin who created it leaves, is changed to member or is suspended (401 key_creator_removed, key_creator_not_admin, key_creator_banned). GET /api/v2/me shows who a key acts as.

Idempotency#

POST endpoints that create resources accept an Idempotency-Key header (≤ 255 characters). Send a fresh UUID per logical request; if the call times out or the connection drops, retry with the same key and the same body. The action runs at most once.

Which outcomes are replayed:

• 2xx and 4xx are stored and replayed for 24 hours, whether the request succeeded or was rejected (for example a 400 invalid_body or a 404 on one item in a batch). Fix the request and send it with a new key.
• 5xx and 429 are not stored. Retry with the same key and the request runs again.
• A few retryable conflicts are not stored either, such as the 409 notes_conflict / notes_busy on the notes endpoint.

Body comparison ignores key order and whitespace in the JSON.

Secrets are never stored in the replay cache. A replayed API-key creation returns key: null, and a replayed share-link creation returns pin: null; fetch a PIN with GET /api/v2/creators/{id}/share-link?include_pin=true and a write-scope key.

curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"accounts": [{"platform": "tiktok", "handle": "charlidamelio"}]}' \
  "https://www.trackagoat.com/api/v2/projects/<id>/creators"

API versioning#

The current version is v2. All endpoints live under /api/v2/.

v1 has been removed. Every /api/v1/* path now returns 410 Gone with a pointer to its successor:

{
  "data": null,
  "error": "API v1 has been removed. Use /api/v2 (see /docs/api-reference/overview).",
  "meta": { "code": "api_version_removed", "successor": "/api/v2" }
}

The response also carries a Link: </api/v2>; rel="successor-version" header. If you are migrating from v1, the biggest change is the accounts model: a creator no longer has a tiktok_handle. It carries an accounts[] array, and you create creators with a list of accounts.

Available endpoints#

For the full machine-readable spec, download /api/v2/openapi.json.

Creators#

Accounts#

Videos#

Content Groups#

Campaigns, Projects, Goals#

Organizations, Members, Invitations, API Keys#

Payouts#

Analytics#

Notes and documents#

See Notes and documents API.

CSV exports#

See CSV exports.

Changelog#