Skip to main content
These shapes mirror the models documented in docs/integrations/ugcinc/data-structures/* inside the core repo and are reused across every Partner API response.

​
Workspace API Key

Represents the credential you create under Workspace → API Keys. Keys inherit the workspace context, so any post you schedule will land in that workspace’s queue and has access to the hosted accounts assigned there.
FieldTypeDescription
public_idstringShort identifier (e.g., gva_live_2ff93c).
secret_last4stringLast four characters of the secret portion, useful for audits.
workspace_idstringWorkspace that owns the key.
workspace_namestringDisplay name in the dashboard.
created_atstring (ISO 8601)Timestamp when the key was issued.
last_used_atstring | nullUpdated whenever the key is used.
permissionsstring[]Currently ["partner_posts"] for all Partner API keys.
{
  "public_id": "gva_live_2ff93c",
  "secret_last4": "b4d5",
  "workspace_id": "ws_prod_01",
  "workspace_name": "Holiday Launch 2025",
  "created_at": "2025-01-12T15:32:11.402Z",
  "last_used_at": "2025-01-21T08:14:03.009Z",
  "permissions": ["partner_posts"]
}

​
Social Account (BYO + Hosted)

Returned by GET /accounts and referenced when scheduling posts. Account IDs are UUIDs.
FieldTypeDescription
idstring (UUID)Workspace-scoped account identifier.
platformstringtiktok, instagram, etc.
typestringbyo (user-connected) or hosted (Genviral-managed).
usernamestringHandle shown on the platform.
display_namestringFriendly label surfaced in the dashboard.
statusstringactive, paused, revoked, etc.
workspace_idstringWorkspace that owns the account (mirrors authenticated key).
{
  "id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
  "platform": "tiktok",
  "type": "hosted",
  "username": "ugc_trends_42",
  "display_name": "Hosted Trends 42",
  "status": "active",
  "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac"
}

​
Post

Created via POST /posts, retrieved via GET /posts and GET /posts/{id}.
FieldTypeDescription
idstringUnique post ID (post_*).
statusstringdraft, pending, scheduled, retry, posted, failed, partial.
captionstringCross-platform caption.
scheduled_atstring | nullTarget publish timestamp.
created_atstringISO timestamp when the post was created.
accountsobjectSummary + per-account states (see below).
mediaobjectMirrors the create/update payload (type + url/urls).
music_urlstring | nullTikTok post URL applied to the audio track.
{
  "id": "post_789",
  "caption": "Holiday drops start Monday!",
  "status": "scheduled",
  "scheduled_at": "2025-02-01T15:00:00Z",
  "created_at": "2025-01-20T12:05:11.205Z"
}

​
Media

Returned exactly as submitted to POST /posts and PATCH /posts/{id}:
FieldTypeDescription
typestringvideo or slideshow. Determines which property appears below.
urlstringPresent when type="video". Points to the ingested/validated clip.
urlsstring[]Present when type="slideshow". Ordered list of image URLs (1–35 entries).
When BYO accounts are present, Genviral re-hosts the assets behind the scenes so these URLs point to first-party Cloudflare R2 buckets. Hosted-only posts reuse the URLs you provided once reachability is confirmed.

​
Account States

Each post stores a normalized state for every targeted account (from social_post_accounts):
FieldTypeDescription
account_idstringID from GET /accounts.
statusstringOne of draft, pending, scheduled, retry, posted, failed, partial.
published_atstring | nullTimestamp of successful publish.
published_urlstring | nullPlatform URL when the provider shares one (hosted creators).
error_messagestring | nullLast error returned by the platform.
last_attempted_atstring | nullWhen the scheduler last touched this account.
{
  "accounts": {
    "total": 2,
    "states": [
      {
        "account_id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
        "status": "scheduled",
        "published_at": null,
        "published_url": null,
        "error_message": null,
        "last_attempted_at": null
      },
      {
        "account_id": "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089",
        "status": "scheduled",
        "published_at": null,
        "published_url": null,
        "error_message": null,
        "last_attempted_at": null
      }
    ]
  }
}

​
Stats Snapshot

Analytics endpoints (and UI exports) reuse the same structures outlined in docs/integrations/ugcinc/data-structures/account-stat.md and post-stat.md.
FieldTypeDescription
account_stats.idstringUnique stat row.
account_stats.account_idstringLinks back to the workspace account.
account_stats.followersnumber | nullFollowers at the time of capture.
account_stats.viewsnumber | nullAggregated views across all posts.
post_stats.idstringUnique per-post stat row.
post_stats.post_idstringLinks to the Genviral post.
post_stats.viewsnumber | nullViews for the specific post.
post_stats.likesnumber | nullLikes for the specific post.
created_atstringSnapshot timestamp.
{
  "account_stats": {
    "id": "acc_stat_1",
    "account_id": "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089",
    "followers": 15420,
    "views": 1250000,
    "likes": 89500,
    "created_at": "2025-01-19T10:00:00Z"
  },
  "post_stats": {
    "id": "post_stat_1",
    "post_id": "post_789",
    "views": 48200,
    "likes": 3200,
    "created_at": "2025-01-21T04:00:00Z"
  }
}
Use external_id on posts to map Genviral stats back to your own manifest or CMS IDs. The combination of workspace_id, external_id, and account_id is sufficient to reconstruct any analytics roll-up you need.