API

Three on-ramps. Same data.

Ounie accounts hit REST endpoints with a bearer token. AI assistants connect via MCP and get a native tool surface. One-off scripts can skip the account and pay per call via x402 in USDC. All three return the same normalized creator rows.

POST/api/scrape

auth: Bearer

Start a creator-discovery job

Returns a job_id immediately. The actual run completes async (1–3 minutes); poll /api/jobs/{id} or wait on the webhook.

Body

{
  "search_kind": "hashtag",            // hashtag | location | user_followers | user_following
  "query": "veganrecipes",
  "max_creators": 1000,
  "enrichment": true,
  "min_followers": 5000,
  "max_followers": 250000,
  "language": "en",
  "webhook_url": "https://your-host.com/hook"   // optional
}

Response

{ "ok": true, "job_id": "job_01HX...", "credits_reserved": 1500 }

GET/api/jobs/{id}

auth: Bearer

Check job status

Returns the job row plus a 10-minute signed download URL once succeeded.

Response

{
  "job": { "status": "succeeded", "results_count": 842, ... },
  "preview_url": "https://...presigned..."
}

GET/api/jobs/{id}/export?format=csv|json

auth: Bearer

Download the dataset

Streams the file directly. CSV is the default; JSON returns the full normalized shape.

POST/api/x402/scrape

auth: none · x402

Pay-per-call (agents)

No account, no API key. Returns 402 with payment terms; sign and retry with X-Payment header. Synchronous; capped at 500 creators per call.

Body

{
  "search_kind": "hashtag",
  "query": "skincare",
  "max_creators": 50,
  "enrichment": false
}

Response

// 402 Payment Required (initial)
{ "x402Version": 1, "accepts": [{ "scheme":"exact", "network":"eip155:8453", "maxAmountRequired": "1000000", ... }] }

// 200 OK (after settled X-Payment header)
{ "ok": true, "count": 47, "creators": [...], "payment": { "tx_hash": "0x..." } }

HTTP/api/mcp

MCP · Streamable HTTP + SSE

Model Context Protocol server

Drop our tool surface into any MCP host (Cursor, Claude desktop, ChatGPT GPTs, the Ounie AI Team, the AI SDK). Seven tools: scrape_creators, get_job_status, export_job_results, list_jobs, get_credit_balance, get_pricing, whoami. Auth: Bearer API key minted in the dashboard — or append ?api_key=ick_live_… to the URL for MCP clients that can't set headers. Calls draw your Ounie credits; when the balance runs short the run is refused with a top-up link, so an agent can never overdraw.

Body

// .cursor/mcp.json (Cursor / any Streamable HTTP host)
{
  "mcpServers": {
    "creator-atlas": {
      "url": "https://instagram-creators.ounie.com/api/mcp",
      "headers": { "Authorization": "Bearer ick_live_..." }
    }
  }
}

Response

// Tool call: scrape_creators
{
  "search_kind": "hashtag",
  "query": "veganrecipes",
  "max_creators": 250,
  "enrichment": true,
  "min_followers": 5000,
  "max_followers": 250000
}
→ { "ok": true, "job_id": "...", "credits_reserved": 375, "poll_with": { ... } }

// One request. Streaming results.
const res = await fetch("https://instagram-creators.ounie.com/api/scrape", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ${API_KEY}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    search_kind: "hashtag",
    query: "veganrecipes",
    max_creators: 1000,
    min_followers: 5000,
    max_followers: 250000,
    enrichment: true,
  }),
});

const { job_id } = await res.json();
// → poll /api/jobs/${job_id} or wait on the webhook

Schema

Every creator row.

{
  "username": "plantbasedjane",
  "fullName": "Plant-Based Jane",
  "bio": "vegan recipes · cookbook out now",
  "externalUrl": "https://plantbasedjane.co",
  "followers": 128400,
  "following": 423,
  "posts": 812,
  "verified": false,
  "business": true,
  "category": "Food & Beverage",
  "bioEmail": "jane@plantbasedjane.co",
  "contactEmail": "jane@plantbasedjane.co",
  "contactPhone": "",
  "location": "Brooklyn, NY",
  "profileUrl": "https://www.instagram.com/plantbasedjane/",
  "profilePicUrl": "https://...",
  "engagementRate": 0.0421,
  "avgLikes": 4823, "avgComments": 595,
  "hashtags": ["#vegan","#plantbased",...],
  "mentions": ["@oatly","@elmhurst1925",...]
}

Availability

What happens when the discovery engine is down.

A scheduled probe checks the discovery engine. While it is unavailable we refuse up front and charge nothing: no quote is issued, no credits are reserved, and no job is created.

You get 503 with {"error":"upstream_unavailable"} and a Retry-After header. On the x402 rail this deliberately carries no payment offer, so an agent never signs an authorization for work that cannot complete. Service resumes on its own.

Rate limits

· REST: 60 jobs / min / key
· x402: 5 req / sec / payer address
· Max creators per job: 50,000 (REST) · 500 (x402)