Core concepts

The reference pages describe every field the API has. This page describes what those fields are about: the handful of objects the whole surface is built from, and how they relate. It’s background rather than a procedure — nothing here is a step to follow.

If you’ve used the Archive app, most of this will be familiar under different names. The glossary at the end maps the two vocabularies, including the places where the same word means different things on each side.

Workspaces

A workspace is one brand, or one region of a brand — the boundary the WORKSPACE-ID header selects. Every operation except workspaces reads from exactly one workspace, and nothing crosses that line: an item, a creator, or a saved view belongs to a workspace and is invisible from any other.

An organization can hold many workspaces. A token issued to an organization reaches all of them, one per request, but they stay separate in every other respect — including rate limits, where each workspace draws from its own bucket rather than sharing the organization’s. See Workspaces for the header mechanics and Rate limits & plans for the bucket model.

A workspace is also what defines the content Archive captures for you. Workspace exposes the hashtags, mentions, and keywords it tracks, plus its integrations — the connected social accounts. Archive monitors those and captures what matches, which is why items returns your tracked universe rather than the whole platform.

Items: the content

An Item is a single captured piece of social content — a post, a Reel, a Story, a TikTok video, a YouTube Short. It carries what the platform published (caption, hashtags, mentions, takenAt, location) alongside what Archive derived from it (transcriptions, currentEngagement, customAttributes).

Items have more than one identifier, and they don’t mean the same thing:

• id — the item in Archive. This is what you pass to other operations.
• externalId — the platform’s own ID for the content.
• mediaItemId — the parent post. Carousel frames that belong to one post share it, so use it to regroup them.
• originalUrl — the post on the platform. It’s null for content with no public URL, such as Instagram Stories, and it stops resolving when the post is deleted or the account goes private.
• archivePublicUrl — Archive’s permalink, which keeps resolving after the original doesn’t.

Platform and format are separate

provider is the platform (INSTAGRAM, TIKTOK, YOUTUBE, INTERNAL). type is the format (POST, REEL, SHORT, STORY). They’re independent: a TikTok video comes back as provider: TIKTOK with whichever format value fits, not as a single fused value.

Filtering does fuse them, and this is the most common cause of a query that returns nothing:

Engagement

currentEngagement is the latest metrics snapshot for an item; engagementHistory returns the series behind it. Two fields there are easy to misread:

• views and impressions are not the same field. views is the platform’s view count; impressions covers views, plays, or estimated impressions depending on the source. Don’t assume they agree, and don’t substitute one for the other.
• earnedMediaValue is in cents. Divide by 100 before you show it as currency.

Transcriptions

Video items carry transcriptions — the spoken content as plain text, keyed to the media it came from by mediaContentId. This is what makes speech searchable: the FUZZY_TRANSCRIPTION super-search mode matches against these, not against captions. See Filtering & search.

Creators and social profiles

These two are distinct objects, and confusing them is the most expensive mistake in this data model.

A Social Profile is one account on one platform: accountName (the handle), provider, followers, verified, and any contact details Archive has (email, phoneNumbers).

A Creator is the person behind those accounts — one unified record per workspace, with socialProfiles listing every account linked to them. The link runs both ways: SocialProfile.creator points back, though it’s nullable, because a profile that has no creator record in this workspace returns null.

Items reference both. Item.socialProfile is the account that posted; Item.creator is the person behind it.

Collections, views, and view groups

Three different ways to organize a workspace, easily confused because the app presents them side by side.

A Collection is a manual grouping. Membership is explicit — you put items in with addItemToCollections and take them out with removeItemFromCollections — and itemCount tells you how many are in it. A Collection never evaluates a rule; it holds exactly what you put there.

A view is the opposite: a saved query, stored once and re-run every time you read it. There are three kinds, one per object they list — ContentView, SocialProfileView, and CreatorView. A view’s id is a filter-preset UUID, which is what you pass as presetId. Deleting a view never deletes content; the items survive and lose only that one grouping.

A View Group is a folder. One group can hold Collections and all three kinds of view at once, each in its own ordered list.

Views don’t all filter the same way

The three view types store the same fields but don’t honor them equally on read:

For Social Profile and Creator views, filters is stored and echoed back to you verbatim, but never evaluated. A view that narrows correctly in the app can therefore return an unnarrowed list through the API. To build one that actually filters, express the narrowing as customAttributeConditions.

Note also that presetId is exclusive on items: supply it and the filter, sorting, and customAttributeConditions arguments are ignored, because the saved view defines the query entirely. Filtering & search covers both behaviors in more detail.

Custom attributes and AI Filters

customAttributes is a free-form JSON object carried by both items and creators — your own metadata, the CRM layer on top of captured content. Because it’s opaque JSON, the keys inside it are described separately, by customAttributeSchemas: each entry gives a key, a human-readable name, and a type.

Some attributes are filled in by AI Filters rather than by a person. A schema entry marks these with aiGenerated: true, and the item’s aiFilterReasons carries the model’s explanation for the value it assigned, paired to the attribute by key. An explanation can be null when the run recorded none.

To query on custom attributes, use the top-level customAttributeConditions argument — a sibling of filter, not a field inside it. See Filtering & search.

UI ↔ API glossary

Where the app and the API use different words for the same thing, or the same word for different things:

Where to go next

• Getting started — your first three requests, end-to-end.
• Filtering & search — putting the item and custom-attribute model to work.
• Workspaces — the WORKSPACE-ID model in full.
• API reference — every query, mutation, and type.
• MCP overview — the same objects, exposed to agents as tools.