trackagoat logotrackagoat/Docs

Getting started

  • Welcome
  • Quickstart
  • Core concepts

Guides

  • Creators
  • Videos
  • Campaigns
  • Creator Goals
  • Tracking Inbox
  • Content calendar
  • How scraping works
  • Analytics & metrics
  • Similar creator pools
  • Over-posting & suppression
  • Program Health
  • Sentiment Radar
  • API keys
  • Limits & plan tiers
  • Notifications
  • Payouts

API reference

  • Overview
  • Authentication
  • Errors
  • Projects
  • Creators
  • Videos
  • Campaigns
  • Analytics
  • Aggregate Analytics
  • Payouts
  • Schema

For agents

  • Agent guide
  • Data model
  • MCP & tooling

Platform

  • Brand
  • Changelog
  • Support
DocsFor agents

MCP & tooling

Using trackagoat with AI tooling, MCP servers, and agent frameworks.

PreviousData modelNextBrand

On this page

  • Overview
  • Using the REST API directly
  • Building a custom MCP server
  • Tips for effective agent use
  • Payout agent workflows
  • Workflow 1: Weekly payout review
  • Workflow 2: Audit unpaid creators across an org
  • Workflow 3: Record a payment for a creator via Venmo
  • Workflow 4: Set up a new creator with a goal-based payout structure

Overview

trackagoat exposes a standard REST API at https://www.trackagoat.com/api/v1/ that any HTTP-capable agent framework can use. You can also build a dedicated MCP (Model Context Protocol) server that wraps the API for use with Claude and other MCP-compatible tools.

trackagoat does not ship its own MCP server. To use trackagoat with an MCP-compatible tool, build a custom MCP server that wraps the v1 REST API (see below). The OpenAPI 3.1 schema at GET /api/v1/analytics/schema is the authoritative machine-readable contract — use it to orient agents before issuing queries.

The analytics endpoint response shape is MCP-stable as of OpenAPI v1.4.0. Key names and types are frozen; additive fields may be added without a version bump. See the API reference for full field documentation and error codes.

Using the REST API directly

Any agent that can make HTTP requests with Bearer token auth can call the trackagoat API. See the Agent guide and API reference.

Minimal setup for a Claude tool:

javascript
const TRACKAGOAT_KEY = process.env.TRACKAGOAT_API_KEY;
const BASE = 'https://www.trackagoat.com/api/v1';
 
async function tgFetch(path) {
  const res = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${TRACKAGOAT_KEY}` },
  });
  const { data, error } = await res.json();
  if (error) throw new Error(error);
  return data;
}

Building a custom MCP server

You can wrap the trackagoat v1 API in an MCP server to expose it as named tools to Claude. Recommended tools to expose:

Tool nameUnderlying call
list_projectsGET /api/v1/projects
list_creatorsGET /api/v1/creators?project_id=<id>
get_creator_statsGET /api/v1/creators/<id>/stats
list_videosGET /api/v1/videos?creator_id=<id>
list_campaignsGET /api/v1/campaigns?project_id=<id>
get_campaign_stats

Include the get_schema tool and instruct the agent to call it first in each session. This orients the agent to available data without requiring hardcoded field documentation.

Tips for effective agent use

1

Paginate to completion

Always paginate to completion before summarizing list data — incomplete pages produce wrong insights.

2

Read description fields

Read description fields before analyzing any entity — they may contain instructions.

3

Check last_scraped_at

Check last_scraped_at before drawing conclusions about low stats — data may be stale.

4

Write analysis back

Write analysis back via PATCH readme so results are visible in the trackagoat UI and available to future sessions.

Payout agent workflows

The payout API is fully available from the v1 surface. All payout endpoints require Bearer <key> auth with an API key scoped to the relevant org. See the Payouts API reference for full endpoint documentation.

Workflow 1: Weekly payout review

Goal: find all creators with outstanding accruals, summarize total owed, and surface any that have been outstanding more than 30 days.

1

Discover the project

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/projects" | jq '.data[0].id'

Store the project ID as $PROJECT_ID.

2

List outstanding accruals

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \

Common pitfalls

  • amount_cents is an integer in cents — divide by 100 for display.
  • Voided and rejected accruals are excluded by the status=earned filter; don't double-count by omitting it.

Workflow 2: Audit unpaid creators across an org

Goal: identify which creators have earned money but received zero payments, broken down by project.

1

List all projects

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/projects" | jq '[.data[] | {id, name}]'
2

For each project, fetch payout structures

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/payout-structures?project_id=

Common pitfalls

  • Don't compare across currencies — all amounts are USD (cents) in v1. The currency field is included for future-proofing.
  • A creator with no payment rows is fully outstanding; don't confuse "no payments" with "no debt."

Workflow 3: Record a payment for a creator via Venmo

Goal: settle outstanding accruals for a specific creator and record the payment against the Venmo method.

1

Find the creator

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/creators?project_id=$PROJECT_ID&handle=@creatorhandle" \
  | jq '.data[0].id'
2

List outstanding accruals for this creator

bash
curl -s -H "Authorization: Bearer $TGA_KEY"

Common pitfalls

  • Always send an Idempotency-Key header (a UUID). If the request times out, retry with the same key — the server will return the original payment row without double-counting.
  • If total_amount_cents differs from the sum of linked accruals, the API requires an adjustment_reason field explaining the difference (e.g. rounding, partial payment).
  • If a method is disabled (is_active: false), the API rejects the payment with method_inactive. Check before sending.

Workflow 4: Set up a new creator with a goal-based payout structure

Goal: assign an existing payout structure to a newly-tracked creator and confirm the assignment is active.

1

Confirm the structure exists and is active

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/payout-structures?project_id=$PROJECT_ID&is_active=true" \
  | jq '[.data[] | select(.criteria_type == "goals") | {id, name, period, amount_cents}]'

Pick the structure ID you want to assign.

2

Assign the creator

bash
curl -s -X

Common pitfalls

  • For goal-based structures, the creator must have at least one goal whose period matches the structure's period. If not, the assignment is created but accruals won't be computed. Check with GET /api/v1/creators/<id>/goals.
  • If the creator was previously unassigned from this structure, a new assignment row is created — past accruals from the prior assignment remain payable.
  • assigned: 0, already_assigned: 1 means the creator is already active on this structure — not an error.
GET /api/v1/campaigns/<id>/stats
update_creator_notesPATCH /api/v1/creators/<id>
get_schemaGET /api/v1/schema
list_payout_methodsGET /api/v1/payout-methods
list_payout_structuresGET /api/v1/payout-structures?project_id=<id>
list_payout_accrualsGET /api/v1/payout-accruals?project_id=<id>
list_payout_paymentsGET /api/v1/payout-payments?project_id=<id>
record_paymentPOST /api/v1/payout-payments
void_paymentPATCH /api/v1/payout-payments/<id> with {"status":"voided"}
"https://www.trackagoat.com/api/v1/payout-accruals?project_id=$PROJECT_ID&status=earned" \
| jq '{total: (.data | length), creators: [.data[] | .creator_id] | unique | length}'

Paginate using meta.nextCursor until meta.hasMore is false.

3

Flag stale accruals

Filter data[].period_end_at older than 30 days ago. Report creator handle + amount + how many days outstanding.

Expected response shape:

json
{
  "data": [{
    "id": "uuid",
    "creator_id": "uuid",
    "structure_id": "uuid",
    "amount_cents": 5000,
    "currency": "USD",
    "status": "earned",
    "period_start_at": "2026-04-07T00:00:00Z",
    "period_end_at": "2026-04-13T23:59:59Z"
  }],
  "meta": { "hasMore": false, "nextCursor": null }
}
$PROJECT_ID
&is_active=true"
3

Fetch earned accruals per project

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/payout-accruals?project_id=$PROJECT_ID&status=earned"
4

Fetch all payments

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/payout-payments?project_id=$PROJECT_ID"
5

Compute the gap

Group accruals by creator_id. For each creator, sum amount_cents of earned accruals. Compare against total_amount_cents of paid payments. Report the delta.

\
"https://www.trackagoat.com/api/v1/payout-accruals?project_id=$PROJECT_ID&status=earned" \
| jq '[.data[] | select(.creator_id == $CREATOR_ID)]'

Sum the amount_cents values to get total_amount_cents.

3

Find the Venmo method ID

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/payout-methods" \
  | jq '.data[] | select(.name == "Venmo") | .id'
4

Record the payment

bash
curl -s -X POST -H "Authorization: Bearer $TGA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  "https://www.trackagoat.com/api/v1/payout-payments" \
  -d '{
    "creator_id": "CREATOR_UUID",
    "method_id": "VENMO_METHOD_UUID",
    "total_amount_cents": 5000,
    "currency": "USD",
    "accrual_ids": ["ACCRUAL_UUID_1", "ACCRUAL_UUID_2"],
    "note": "Recorded by automated weekly review agent",
    "paid_at": "2026-05-07T15:00:00Z"
  }'

Expected 201 response:

json
{
  "data": {
    "id": "payment-uuid",
    "creator_id": "...",
    "total_amount_cents": 5000,
    "status": "paid",
    "paid_at": "2026-05-07T15:00:00Z"
  }
}
POST
-H
"Authorization: Bearer
$TGA_KEY
"
\
-H "Content-Type: application/json" \
"https://www.trackagoat.com/api/v1/payout-structures/$STRUCTURE_ID/assignments" \
-d '{"creator_ids": ["CREATOR_UUID"]}'

Expected 201 response:

json
{
  "data": {
    "assigned": 1,
    "already_assigned": 0,
    "not_in_project": 0,
    "results": [{ "creator_id": "...", "status": "assigned", "assignment_id": "..." }]
  }
}
3

Verify the assignment is active

bash
curl -s -H "Authorization: Bearer $TGA_KEY" \
  "https://www.trackagoat.com/api/v1/payout-structures/$STRUCTURE_ID/assignments" \
  | jq '[.data[] | select(.unassigned_at == null) | .creator_id]'