Connecting accounts

Create a connect link

POST /instagram/connect-links creates a connect link for Instagram. POST /x/connect-links creates a connect link for X. POST /youtube/connect-links creates a connect link for YouTube. The platform is in the path, so the request body does not name it. You can send external_user_id, redirect_uri, force_reauth, and metadata. Use force_reauth: true when users can choose another account on the platform. The response contains a cl_ ID, an authorization URL, the platform, the external user ID, and an expiry time. A connect link expires after 10 minutes.

Verify the outcome

The redirect query contains connect_id. Bind this ID to the browser that created it. Then call GET /instagram/connect-links/{connect_link_id} or GET /x/connect-links/{connect_link_id} or GET /youtube/connect-links/{connect_link_id} from your server. Use the path of the platform that created the link. A connect link ID from another platform returns 404. The response contains an open-string status, a nullable message, and a nullable account summary. Known statuses are pending, expired, connected, already_linked, external_user_id_mismatch, needs_professional, and missing_permissions. Both of the last two apply only to Instagram. missing_permissions means the user did not allow access to insights on the Instagram consent screen. We need insights to read views, so we do not connect the account. Send the user through a new connect link and ask them to keep every permission on. message explains this. Do not use the redirect query to grant access. Use the verified API response.

Connect an X account

An X connect link works like an Instagram connect link.

Call POST /x/connect-links. The body is the same as for Instagram.
Send the user to the returned url.
The user signs in with X and approves access.
We connect the X account to your workspace. We use your external_user_id for the account. Without it, we use the X username.
We send the user to redirect_uri. The query contains status and connect_id. A connected result also contains username.
Call GET /x/connect-links/{connect_link_id} to read the verified result.

Without redirect_uri, the user sees a short result page. With force_reauth: true, X shows its sign-in screen. The user can then sign in to a different X account. Known statuses for X are pending, expired, connected, already_linked, and external_user_id_mismatch.

Connect a YouTube account

A YouTube connect link works like an Instagram connect link.

Call POST /youtube/connect-links. The body is the same as for Instagram.
Send the user to the returned url.
The user signs in with YouTube, picks a channel, and approves read access.
We connect the YouTube channel to your workspace. We use your external_user_id for the account. Without it, we use the channel handle. A channel without a handle uses its channel ID.
We send the user to redirect_uri. The query contains status and connect_id. A connected result also contains username.
Call GET /youtube/connect-links/{connect_link_id} to read the verified result.

Without redirect_uri, the user sees a short result page. YouTube shows its account chooser and asks for approval on every connect, so force_reauth changes nothing for YouTube. The user can pick a different channel each time. The approval screen asks for two permissions: read access to the channel, and access to its audience data. The user can turn the audience permission off and still connect. We then track views, but we cannot read the audience of the channel’s tracked media. Known statuses for YouTube are pending, expired, connected, already_linked, and external_user_id_mismatch.

Account object

{
  "id": "acct_3f9c0a1b2c3d4e5f60718293",
  "platform": "instagram",
  "platform_user_id": "17841400008460056",
  "username": "acme.studio",
  "external_user_id": "customer_8f3a2c19",
  "connection": { "status": "active", "reason": null },
  "tracking": {
    "status": "active",
    "parked_reason": null,
    "next_read_at": "2026-09-15T02:00:00.000Z"
  },
  "capabilities": ["media_stats", "media_comments"],
  "metadata": { "plan": "pro" },
  "latest_as_of": "2026-09-14T00:00:00.000Z",
  "connected_at": "2026-09-10T14:22:18.000Z",
  "created_at": "2026-09-10T14:22:18.000Z"
}

connection describes the creator sign-in. It is null without that sign-in. Its status is active, needs_reauth, or revoked. connection.reason says why the creator must connect again. It is null unless the status is needs_reauth. It is an open string. Known values:

Reason	What happened	What the creator does
`token_invalid`	The sign-in expired or was revoked.	Connect again.
`insights_permission_missing`	The creator did not allow access to insights. We cannot read views without it.	Connect again and keep every permission on.
`account_not_professional`	The Instagram account was switched to a personal account.	Switch back to a Business or Creator account, then connect again.

When the creator connects again, the tracked media held for that reason start again by themselves. tracking describes account-level collection. It is null until the first eligible tracked media starts collection. Its status is active, parked, or stopped. capabilities lists the data that this kind of connection can read. Treat each capability as an open string. An account without a connection has an empty list today. A capability does not prove that data exists for this account. For example, an account that signed in before we asked for comment access has media_comments, but we cannot read its comments until the creator connects again. Until then, comments.captured_at on its tracked media stays null.

X accounts

An X account has platform: "x". platform_user_id is the numeric X user ID.

{
  "id": "acct_7b2e4d6f8a0c1e3a5c7e9b1d",
  "platform": "x",
  "platform_user_id": "1456789012345678901",
  "username": "acmestudio",
  "external_user_id": "customer_8f3a2c19",
  "connection": { "status": "active", "reason": null },
  "tracking": null,
  "capabilities": ["media_stats"],
  "metadata": { "segment": "creator" },
  "latest_as_of": null,
  "connected_at": "2026-09-10T14:22:18.000Z",
  "created_at": "2026-09-10T14:22:18.000Z"
}

capabilities is ["media_stats"]. We do not read comments on X. tracking is always null. We do not read audience or insights for X accounts. See Audience and insights.

YouTube accounts

A YouTube account has platform: "youtube". platform_user_id is the channel ID, which starts with UC. username is the channel handle without @. A channel without a handle has its channel ID as username.

{
  "id": "acct_3d5f7a9b1c2e4f6a8b0c1d3e",
  "platform": "youtube",
  "platform_user_id": "UC4R8DWoMoI7CAwX8_LjQHig",
  "username": "acmestudio",
  "external_user_id": "customer_8f3a2c19",
  "connection": { "status": "active", "reason": null },
  "tracking": null,
  "capabilities": ["media_stats", "media_demographics"],
  "metadata": { "segment": "creator" },
  "latest_as_of": null,
  "connected_at": "2026-09-10T14:22:18.000Z",
  "created_at": "2026-09-10T14:22:18.000Z"
}

capabilities includes media_demographics when the user gave access to the channel’s audience data. Without it, capabilities is ["media_stats"] and geo tracked media of the account report demographics.availability as not_tracked. To fix this, send the user through a new connect link and ask them to allow audience access. We do not read comments on YouTube. tracking is always null. We read the audience of each geo tracked media, not of the account. See Audience and insights.

Find accounts

Use GET /instagram/accounts?external_user_id= to find the Instagram accounts for one user. Use GET /x/accounts?external_user_id= to find the X accounts. Use GET /youtube/accounts?external_user_id= to find the YouTube accounts. You can also filter by username. The username filter is a case-insensitive exact match. Use GET /{platform}/accounts/{account_id} for one account. Use PATCH /{platform}/accounts/{account_id} to merge metadata. An account ID only works under its own platform path.

Getting Started

API Reference

Developer Guides

Create a connect link

Verify the outcome

Connect an X account

Connect a YouTube account

Account object

X accounts

YouTube accounts

Find accounts

​Create a connect link

​Verify the outcome

​Connect an X account

​Connect a YouTube account

​Account object

​X accounts

​YouTube accounts

​Find accounts

Create a connect link

Verify the outcome

Connect an X account

Connect a YouTube account

Account object

X accounts

YouTube accounts

Find accounts