Goal Compliance

Managing goals (write endpoints)

POST /api/v1/creators//goals

Create a goal for a creator. Requires the write scope.

bash

curl -X POST \
  -H "Authorization: Bearer tga_<key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"metric": "views", "period": "weekly", "target_value": 500000}' \
  https://www.trackagoat.com/api/v1/creators/<creatorId>/goals

Field	Type	Description
`metric`	`posts` \| `views` \| `engagement` \| `followers`	What to measure.
`period`	`daily` \| `weekly` \| `monthly`	Evaluation window.
`target_value`	integer > 0	Target number per period.
`start_date`	YYYY-MM-DD	Optional. Goals with a future start date show an advisory until active.
`end_date`	YYYY-MM-DD	Optional end date.

PATCH /api/v1/creators//goals/

Update a goal. At least one field required. Requires the write scope.

DELETE /api/v1/creators//goals/

Permanently delete a goal. Requires the write scope.

Compliance overview (read endpoint)

The goal compliance endpoint returns per-creator, per-goal progress results for a project. Each result includes:

The goal's current actual value and target
A status (on_track, behind_pace, at_risk, missed, completed)
An advisory block explaining why the displayed progress may not be final

For a project-wide roll-up (counts only), use /aggregate/goal-compliance instead.

GET `/api/v1/projects/:projectId/goal-compliance`

Returns compliance results for all active creators in a project, grouped by creator.

Request

bash

curl -H "Authorization: Bearer tga_<key>" \
  "https://www.trackagoat.com/api/v1/projects/<projectId>/goal-compliance"

Query parameters

Parameter	Type	Default	Description
`creator_id`	UUID	—	Restrict results to a single creator
`period`	`daily` \| `weekly` \| `monthly`	all	Filter to goals of this period type
`reference_date`	YYYY-MM-DD	today (org tz)	Evaluate goals as of this date

Response

json

{
  "data": [
    {
      "creator": {
        "id": "uuid",
        "tiktok_handle": "sarah.b8520",
        "display_name": "SarahBD",
        "avatar_url": "https://..."
      },
      "compliance": [
        {
          "goal": {
            "id": "uuid",
            "creator_id": "uuid",
            "project_id":

Status values

Status	Meaning
`on_track`	Projected to meet or exceed target by period end
`behind_pace`	Below projected pace but above the 70% at-risk threshold
`at_risk`	Significantly behind pace (below 70% of projected)
`completed`	Period has ended and target was met
`missed`	Period has ended and target was not met

The `advisory` object

Every compliance result includes an advisory block. When has_advisory is false, the displayed progress is likely final and the object can be ignored. When true, the messages array contains one human-readable explanation per active flag.

Advisory flags

Field	Type	Condition
`period_in_progress`	boolean	Current wall-clock time is before the period end. Actual counts will grow until period close.
`period_recently_ended`	boolean	Period ended within the last 48 hours. Late-period posts may still be processing through scrape.
`scrape_stale`	boolean	Creator's stats scrape is turning stale or overdue. Views, engagement, or follower counts may undercount until the next scrape runs.
`not_yet_started`	boolean	The goal has a `start_date` set in the future. No data has accrued yet.
`has_advisory`	boolean

Advisory context fields

Field	Type	Description
`period_start`	ISO timestamp	UTC start of the current period
`period_end`	ISO timestamp	UTC end of the current period
`hours_until_period_end`	number \| null	Hours remaining until period closes; `null` if period already ended
`hours_since_period_end`	number \| null	Hours elapsed since period closed; `null` if period is still open
`scrape_freshness`	object \| null

Relationship to aggregate endpoint

Use case	Endpoint
Dashboard summary (counts only)	`GET /api/v1/analytics/aggregate/goal-compliance`
Per-creator, per-goal detail with advisories	`GET /api/v1/projects/:id/goal-compliance`
Single creator's goals	`GET /api/v1/projects/:id/goal-compliance?creator_id=<uuid>`

Goals