Skip to main content
Use this endpoint to manage the tracked accounts used by analytics summary and post reporting.

​
GET Behavior

  • Returns all targets scoped to the authenticated key (workspace scope for workspace keys, personal scope for personal keys).
  • Includes last snapshot/refresh status and free_refresh_available.
  • This dataset is the source of account-level stats shown in the internal UI.

​
POST Body

​
platform
string
required
Supported values: tiktok, instagram, youtube.
​
identifier
string
required
Account identifier/handle to track (for example @brand).
​
alias
string
Optional display name override.

​
Response

​
GET Response Fields

​
workspace_id
string | null
Workspace tied to the API key (null for personal-scope keys).
​
targets
array
Analytics targets with status metadata and last snapshot totals. Each row includes canonical id and a backward-compatible target_id alias.

​
POST Response Fields

​
target
object
Created (or existing) target row.
​
created
boolean
true when a new target was created, false when an existing scoped target was returned.
curl --request POST \
  --url https://www.genviral.io/api/partner/v1/analytics/targets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "platform": "tiktok",
    "identifier": "@brand",
    "alias": "Brand HQ"
  }'

{
  "ok": true,
  "code": 201,
  "message": "Analytics target created",
  "data": {
    "target": {
      "id": "e7a7f417-56db-4320-9e9a-fd6fdabda09d",
      "user_id": "7f026314-7657-4b0f-bb45-8fd4c0b95fd7",
      "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
      "platform": "tiktok",
      "identifier": "@brand",
      "normalized_identifier": "brand",
      "display_name": "Brand HQ",
      "last_refreshed_at": null
    },
    "created": true
  }
}

​
Error Responses

  • 400 invalid_json — request body is not valid JSON
  • 400 invalid_payload — body must be a JSON object
  • 400 — unsupported platform or missing identifier
  • 401/403 — authentication failed or key lacks workspace access
  • 500 — unexpected database/analytics service error
All error responses from analytics endpoints include an error_code field.