Connecting accounts

ClipStake reads Instagram through the account owner’s own authorization. Your end user approves once, and every project in your workspace can then track that account’s media.

Mint a connect link

POST /connect-links returns a URL and nothing else. No row is written yet. A connection is created by the callback, once Instagram returns a code, so links that are generated and never clicked leave nothing behind.

curl --request POST "https://api.clipstake.com/v1/connect-links" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "external_user_id": "your-user-123",
    "redirect_uri": "https://your-app.com/instagram/connected",
    "force_reauth": false
  }'

Field	Notes
`external_user_id`	Optional. Your own id for the person. Opaque to ClipStake, scoped to your workspace. Omit it to use the account’s Instagram handle.
`redirect_uri`	Optional. An absolute URL on your site, where the user lands when the flow ends. Use HTTPS. Omit it and the user sees a ClipStake page that tells them the result.
`force_reauth`	Optional. Show Instagram’s account picker. Off by default.

The response carries an id, the url, and expires_at. A link is valid for 10 minutes. Mint it at the moment the user is about to click it, and keep the id with that user’s session.

Read the result

When the flow ends, the user lands on your redirect_uri with three query parameters: status, username and connect_id. Use them for display only. Anyone can type them into a URL. To act on the result, for example to sign the user in, check that connect_id is the id you stored, then read the result with your API key:

curl "https://api.clipstake.com/v1/connect-links/$CONNECT_ID" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY"

{
  "id": "3f1c9a52-6d1e-4b8a-9f0e-2c7d5a1b8e44.1789398000.Qm8vT2xk3NcR7pLwZ0yH4sFbJ6aUeD1i",
  "status": "external_user_id_mismatch",
  "message": "This Instagram account is already connected under a different external_user_id.",
  "account": {
    "username": "creator_handle",
    "external_user_id": "your-user-456"
  },
  "expires_at": "2026-09-14T11:00:00.000Z"
}

`status` from `GET /connect-links/{id}`

`status`	Meaning
`pending`	The user has not finished yet, or cancelled on Instagram.
`expired`	The link lapsed without a result.
`connected`	The account is connected. `account` names the account and its `external_user_id`.
`external_user_id_mismatch`	The account is already connected in this workspace under a different `external_user_id`. Nothing was changed. `account` names the existing connection, and `message` says what happened.
`already_linked`	Another connect of the same account finished at the same time and won. `account` is `null`. List your accounts to see which user holds it.
`needs_professional`	The account is not a Business or Creator account. Nothing was connected.

message is set only on external_user_id_mismatch. It is null for every other status. Branch on status, not on message.

`status` on the redirect

The redirect’s status query parameter carries the same values, with three differences:

`status`	Meaning
`access_denied`	The user cancelled on Instagram. The API read reports `pending` until the link expires.
`exchange_failed`	ClipStake could not finish the exchange with Instagram. The API read reports `pending` until the link expires. Send the user through a new link.
`already_linked`	Also sent when the browser opens the same finished callback a second time. The API read still reports the first result.

username is sent only when the status is connected, or on a repeat of a connected callback. It is never sent for external_user_id_mismatch.

One connection per account in each workspace

A connection is unique for each workspace and Instagram account. The rules that follow from that:

Same workspace, same external_user_id. This is a reconnect. The existing connection gets the new authorization and keeps its history.
Same workspace, different external_user_id. This is a mismatch. The connect returns external_user_id_mismatch and changes nothing, so one of your users can never take another user’s tracked media.
Different workspace. The connect succeeds. Each workspace gets its own connection and its own authorization.

One external_user_id can hold more than one Instagram account.

Resolve a mismatch

A mismatch means the account already belongs to another of your users.

If it is the same person, sign them in as the user in account.external_user_id.
If it is a different person, handle it in your own support process.

ClipStake does not move a connection from one external_user_id to another.

Use the handle as your user id

If your app has no user id of its own, omit external_user_id. The account is connected under its Instagram handle, and account.external_user_id returns it. When the same person connects again, the connection is refreshed, not duplicated.

When to set `force_reauth`

Instagram authorizes whichever account the browser is already signed in to. For someone who granted the scopes before, it does that without stopping to ask. On a first connect the flag changes nothing. On a second one it decides whether your user picks the account or Instagram picks for them.

If your flow lets one person connect more than one handle, pass force_reauth: true. Without it the consent screen can flash past and reconnect the first account, with no error to explain it.

The connection belongs to the workspace

A connect link is minted with a workspace key, and the connection it creates is reachable from every project in that workspace. Projects separate tracked media, not people.

List connected accounts

curl --get "https://api.clipstake.com/v1/accounts" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --data-urlencode "external_user_id=your-user-123"

Every connected account is listed, including accounts with no tracked media yet.

`connection_status`

Value	Meaning
`active`	The authorization works.
`needs_reauth`	The authorization expired or Instagram rejected it. Reconnect the account.
`revoked`	The user removed access. Reconnect the account.

While a connection is not active, POST /submissions and the audience and insights reads for that account return 409 conflict.

`tracking_status`

Tracking follows submissions. You never start or stop an account directly.

Value	Meaning
`active`	The account has at least one trackable media, so it is being read.
`parked`	Reading is on hold. The usual cause is a connection that needs a reconnect.
`stopped`	No eligible tracked media remains.

Accepting the first eligible media enrolls the account. Pausing or stopping the last one ends collection. There is no account start, pause, or resume endpoint.

Keeping a connection active

ClipStake keeps each connection’s authorization current automatically. You do not need to do anything while the connection is active. An authorization that expires, or that Instagram rejects, moves the connection to needs_reauth. Only a reconnect repairs it.

Reconnecting

To reconnect an account, mint a new connect link with the same external_user_id as the existing connection. Pass force_reauth: true so the user picks the right account on Instagram.

curl --request POST "https://api.clipstake.com/v1/connect-links" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "external_user_id": "your-user-123",
    "redirect_uri": "https://your-app.com/instagram/connected",
    "force_reauth": true
  }'

A reconnect refreshes the existing connection, sets it back to active, and keeps its history. A different external_user_id returns external_user_id_mismatch instead.

What happens to tracked media

Media that was parked because the connection needed a reconnect goes back on the schedule automatically. Each media reads at its next scheduled slot. This applies in every non-archived project of the workspace. Two limits apply:

Automatic resume respects your submission capacity. Media that does not fit stays parked. Resume it after you raise the plan.
Media that was parked because its reads kept failing is not resumed by a reconnect. Resume it yourself. See Tracking media.

Media you paused yourself stays paused.

Getting Started

Guides

Developer Guides

API Reference

Mint a connect link

Read the result

`status` from `GET /connect-links/{id}`

`status` on the redirect

One connection per account in each workspace

Resolve a mismatch

Use the handle as your user id

When to set `force_reauth`

The connection belongs to the workspace

List connected accounts

`connection_status`

`tracking_status`

Keeping a connection active

Reconnecting

What happens to tracked media

​Mint a connect link

​Read the result

​status from GET /connect-links/{id}

​status on the redirect

​One connection per account in each workspace

​Resolve a mismatch

​Use the handle as your user id

​When to set force_reauth

​The connection belongs to the workspace

​List connected accounts

​connection_status

​tracking_status

​Keeping a connection active

​Reconnecting

​What happens to tracked media

Mint a connect link

Read the result

`status` from `GET /connect-links/{id}`

`status` on the redirect

One connection per account in each workspace

Resolve a mismatch

Use the handle as your user id

When to set `force_reauth`

The connection belongs to the workspace

List connected accounts

`connection_status`

`tracking_status`

Keeping a connection active

Reconnecting

What happens to tracked media