Quickstart

This walkthrough takes you from a new API key to tracked media with a growing time series. Every request uses your workspace key as a Bearer token.

Create a key and pick a project

Create a workspace key in the Console, then list the projects that key can reach. A project groups tracked media. Every submission operation names one.

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

{
  "data": [
    {
      "id": "3f1c9f0a-2f2c-4c0f-9a7d-8a1c0c4e5b21",
      "name": "Production",
      "archived_at": null,
      "created_at": "2026-09-01T10:04:11.000Z"
    }
  ]
}

Send your end user to Instagram

Mint an authorization URL for one of your own users. external_user_id is your id for that person. ClipStake stores it and never parses it.

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"
  }'

Open the returned url in the user’s browser. When they approve, ClipStake stores the connection and sends them to your redirect_uri.

The link expires after 10 minutes. Mint it when the user is ready to click it, not in advance. Read Connecting accounts for the account picker and reconnect cases.

Track your first media

Submit canonical Instagram URLs for a connected account. One request takes up to 100 URLs.

curl --request POST "https://api.clipstake.com/v1/submissions" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "3f1c9f0a-2f2c-4c0f-9a7d-8a1c0c4e5b21",
    "username": "creator_handle",
    "urls": ["https://www.instagram.com/reel/DAbc123XyZ/"]
  }'

Each URL gets its own result, so a partly valid request still succeeds:

{
  "data": [
    {
      "shortcode": "DAbc123XyZ",
      "status": "created",
      "submission": {
        "username": "creator_handle",
        "media_id": "17912345678901234",
        "shortcode": "DAbc123XyZ",
        "status": "active",
        "next_read_at": "2026-09-20T18:00:00.000Z"
      }
    }
  ]
}

Read the time series

ClipStake reads the media on your plan’s cadence and keeps every reading.

curl --get "https://api.clipstake.com/v1/submissions/DAbc123XyZ/stats" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --data-urlencode "project_id=3f1c9f0a-2f2c-4c0f-9a7d-8a1c0c4e5b21" \
  --data-urlencode "limit=100"

The first reading lands when the media is first resolved. The next one lands one cadence interval later.

Where to go next

Connecting accounts

Connect links, the account picker, and connection states.

Tracking media

Submission results, statuses, pausing, and resuming.

Audience and insights

Country, age, and gender shares, and daily account metrics.

Errors

The error envelope and every code you can branch on.

Getting Started

Guides

Developer Guides

API Reference

Where to go next

Connecting accounts

Tracking media

Audience and insights

Errors

​Where to go next

Connecting accounts

Tracking media

Audience and insights

Errors

Where to go next