Glossary: UI to API
A reference for mapping what you see in the Archive UI to the corresponding API fields, filters, and queries.
Terminology
| What the UI calls it | What the API calls it | Notes |
|---|---|---|
| Content Views / Saved Views | filterPresets with accessor: MEDIA_DECK | Use the id as presetId in the items query |
| Collections | filterPresets with accessor: COLLECTIONS | Use the id as presetId, or use addItemToCollections / removeItemFromCollections |
| Post Date | takenAt | Must be UTC ending in Z (e.g., 2026-03-01T00:00:00Z) |
| Creator Labels / Tags | customAttributes field (MULTIPLE_SELECT) | Read-only. Resolve option UUIDs via customAttributeSchemas |
| Relationship Status | customAttributes field (SINGLE_SELECT_V3) | Key: collaboration_status. Values are UUIDs |
| Gender / Age | customAttributes fields (SINGLE_SELECT_V3) | Display labels like “Female” or “25-34” are UUIDs — resolve via customAttributeSchemas |
| Instagram Partnership Ad Code | instagramWhitelistingStatus filter | API uses legacy term “whitelisting” |
| Spark Ads Code | tiktokSparkCodeStatus filter | |
| Usage Rights | usageRightsStatus filter | Filter only — cannot send requests via API |
| EMV (dollar amount in UI) | earnedMediaValue (in cents) | Divide by 100 for dollars |
| Est. Views | views field | For Feed Posts and Stories, views are estimated, not platform-reported |
| Virality Score | linearViralityScore | Only for Reels and TikTok. Values: HIGH, MEDIUM, LOW, NOT_VIRAL |
| Favourites | customAttributes.favourite (BOOLEAN) | Exists in the API as a filterable field but has been removed from the Archive UI |
| Normalized Location | Not in API | Not available |
Creator attributes
These are the fields you see when you open a creator’s profile in the Archive UI. In the API, they all live inside customAttributes on the creator object.
| UI Field | API Key | API Type | How to filter |
|---|---|---|---|
| Full Name | full_name | TEXT | { field: "full_name", operator: CONTAINS, type: TEXT, value: "..." } |
| Location | location | TEXT | { field: "location", operator: CONTAINS, type: TEXT, value: "..." } |
| Emails | emails | TEXT_LIST | { field: "emails", operator: CONTAINS, type: TEXT, value: "..." } — use type TEXT not TEXT_LIST |
| Phone Numbers | phone_numbers | TEXT_LIST | Same pattern as emails — use type TEXT |
| Gender | gender | SINGLE_SELECT_V3 | { field: "gender", operator: IS, type: SINGLE_SELECT_V3, value: "<uuid>" } |
| Age | age | SINGLE_SELECT_V3 | Same pattern as gender — value must be UUID |
| Relationship Status | collaboration_status | SINGLE_SELECT_V3 | Same pattern — value must be UUID |
| Labels | labels | MULTIPLE_SELECT | { field: "labels", operator: CONTAINS, type: MULTIPLE_SELECT, value: "<uuid>" } |
| Category | category | MULTIPLE_SELECT | Same pattern as labels |
| Notes | notes | TEXT | Can use IS_EMPTY / IS_NOT_EMPTY operators |
| Favorite | favourite | BOOLEAN | { field: "favourite", operator: IS, type: BOOLEAN, value: true } |
Important: Gender, Age, Relationship Status, and Labels return UUIDs, not readable names. Always call
customAttributeSchemas(entity: CREATOR)first to map UUIDs to labels.
Relationship Status values
The UI groups these into categories, but the API treats them as flat options on the collaboration_status field:
| UI Group | Status | API Value |
|---|---|---|
| In Progress | To Review | UUID (resolve via schema) |
| In Progress | Outreached | UUID |
| In Progress | In Discussion | UUID |
| In Progress | Interested | UUID |
| Active | Contracted | UUID |
| Active | Active | UUID |
| Closed | Not a Fit | UUID |
| Closed | Not Interested | UUID |
| Closed | Not Responsive | UUID |
Content filters: UI to API
| UI Filter | API Parameter | Example |
|---|---|---|
| Platform | filter: { provider: INSTAGRAM } | INSTAGRAM, TIKTOK, YOUTUBE, INTERNAL (manually imported content — uploaded via file or UGC link) |
| Post Type | filter: { itemTypes: [REEL] } | POST, REEL, STORY, TIKTOK, YOUTUBE, YOUTUBE_SHORT |
| Content Type | filter: { contentTypes: [VIDEO] } | IMAGE, VIDEO |
| Post Date | filter: { takenAt: { from: "...", to: "..." } } | UTC dates with Z |
| Post Date “relative to today” | Compute dates before querying | ”Past 7 days” = calculate from as today minus 7 days |
| Engagement (likes, views, etc.) | filter: { engagement: [{ field: LIKE_COUNT, range: { from: 100, to: 5000 } }] } | Fields: LIKE_COUNT, COMMENT_COUNT, MERGED_VIEW_PLAY_COUNT, SHARE_COUNT, ENGAGEMENTS_RATE, IMPRESSIONS_RATE, EARNED_MEDIA_VALUE |
| Hashtag / Mention | filter: { tagsNames: ["hashtag"] } | Array of strings |
| Creator Handle | filter: { accountNames: ["handle"] } | Array of strings |
| Follower Count | filter: { followersCount: { from: 10000, to: 500000 } } | Integer range |
| Verified | filter: { verified: [true] } | Boolean array |
| Creator Location | filter: { creatorLocation: { query: "New York" } } | City, state, or country |
| Content Location | filter: { ugcLocation: { query: "Los Angeles" } } | Name, city, state, or country |
| Usage Rights | filter: { usageRightsStatus: [APPROVED] } | APPROVED, EXPIRED, IN_QUEUE, REJECTED, REQUESTED |
| Spark Code | filter: { tiktokSparkCodeStatus: [APPROVED] } | Same statuses |
| Instagram Whitelisting | filter: { instagramWhitelistingStatus: [APPROVED] } | Same statuses |
| Virality Score | filter: { viralityScore: [HIGH] } | HIGH, MEDIUM, LOW |
| Import Type | filter: { importType: MANUAL } | MANUAL, AUTOMATIC |
| Saved View | presetId: "<view-id>" | Filters are ignored when using presetId |
| Semantic Search | filter: { superSearch: { searchQuery: "...", mode: FUZZY_CAPTION } } | Modes: FUZZY_CAPTION, FUZZY_TRANSCRIPTION, EMBEDDING_CONTENT |
| Label (on content page) | No direct filter | Workaround: query creators by label first, get their accountNames, then filter items by accountNames |
What’s ONLY possible with the API
These capabilities are not available in the Archive UI — they require the API:
| Capability | API Query/Feature | Why it matters |
|---|---|---|
| Engagement history over time | engagementHistory query | See how likes, views, and EMV grew day by day for any post. The UI only shows current metrics. |
| Look up items by URL | itemIdsByUrl query | Translate Instagram, TikTok, and YouTube URLs into Archive item IDs for further querying |
| Historical engagement data (rolling metrics) | engagementHistory query | Pull L3, L7, L14, L30 metrics for any post. The UI CSV export only shows current engagement — not how it changed over time |
| Automated reporting via Google Sheets | API + Google Apps Script | Auto-refresh engagement data on a schedule without opening Archive |
| Custom integrations (Airtable, N8N, etc.) | Any query/mutation | Push Archive data into any external tool |
| Fresh social profile data | socialProfile with fallback: true | Fetch real-time follower counts directly from the platform |
| Semantic/visual similarity search | superSearch with similarMediaContentId | Find content visually similar to a specific post |
What’s NOT in the API
These features exist in the Archive UI but are not available through the API:
| Feature | Status | Alternative |
|---|---|---|
| Campaigns (create, manage, report) | Not available | Use Content Views and Collections as alternatives |
| Creator Search / Discovery | Not available | Only creators already in your workspace CRM are queryable |
| Send Usage Rights requests | Not available | Filter by status only (usageRightsStatus) |
| Send Spark Code requests | Not available | Filter by status only (tiktokSparkCodeStatus) |
| Edit creator attributes (labels, gender, age, etc.) | Read-only | Make changes in the Archive UI |
| Delete content | Not available | — |
| Audience demographics | Not available | — |
| Activity log | Not available | — |
| Favourites | Available in API (customAttributes.favourite), removed from UI | Query/filter via customAttributeConditions |
| Competitor Insights | Not available | — |
| Deep Research Reports | Not available | Use in the Archive UI |
| Post counts per platform (on social profile) | Not available | Count items per provider using the items query |
Last updated on