API

Two on-ramps. Same data.

Ounie accounts hit REST endpoints with a bearer token. AI assistants connect over MCP and get a native tool surface. Both draw the same wallet and return the same normalized creator rows.

There is no x402 pay-per-call rail. A deep scan runs for minutes and resumes across restarts, so it cannot complete inside a single HTTP response — quoting a price for it would mean an agent signing a payment for work that outlives the request.

POST/api/scans

auth: Bearer

Start a scan

Returns a scan_id immediately; the walk runs in the background and resumes where it left off. You are billed 1 credit per upstream request — a ~50-row follower page, one profile lookup per public account, one engagement fetch per looked-up profile. Private accounts are never looked up individually.

Request

{
  "target": "competitor",     // @handle whose followers to mine
  "scan_depth": 50000,        // followers to LOOK AT (max 200000)
  "with_engagement": true     // median engagement; included in the rate
}

Response

{
  "ok": true,
  "scan_id": "8f3c...",
  "credits_reserved": 100000,   // worst case: every scanned profile public
  "typical_settle": 40000,      // what a scan this deep usually costs
  "credits_per_request": 1
}

GET/api/scans/{id}

auth: Bearer

Status, progress and a page of creators

Accepts the same filter params as the export. `total` is every creator the scan found; `matched` is how many survive the current filter — both are returned, because reporting only one makes a working scan look broken.

Response

{
  "scan": {
    "status": "scanning",
    "scanned_count": 21400,   // followers looked at
    "private_count": 12900,   // skipped, free
    "hydrated_count": 8500,   // public profiles looked up
    "matched_count": 8500     // billable creators
  },
  "total": 8500,
  "matched": 316,
  "creators": [ /* ... */ ]
}

GET/api/scans/{id}/export

auth: Bearer

Full results as CSV or JSON

Streamed, and always complete for the active filter. Pass the same filter params you used above and the download matches exactly what you were looking at.

Request

?format=csv
&min_followers=2000&max_followers=5000
&min_engagement=2&min_posts=20
&has_email=1&verified=1&q=fitness

GET/api/scans

auth: Bearer

List your scans

The 100 most recent, newest first.

MCP

Seven tools: start_scan, get_scan, list_scans, export_scan, get_credit_balance, get_pricing (public) and whoami. Hosts that cannot set an Authorization header may pass ?api_key= instead.

For developers & agents

One key. REST or MCP.

Mint a key in the dashboard and it works on both rails. Tool calls draw the same Ounie wallet as the UI, so an agent and a person share one balance and one ledger.

There is no pay-per-call x402 rail, deliberately. A deep scan runs for minutes and resumes across restarts, so it cannot finish inside one HTTP response — quoting it would mean an agent paying for work that outlives the request.

// Start a scan. Returns immediately — a deep scan outlives any request.
const res = await fetch("https://audienceminer.ounie.com/api/scans", {
  method: "POST",
  headers: {
    "Authorization": "Bearer amn_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target: "competitor",   // whose followers to mine
    scan_depth: 50000,      // followers to LOOK AT, not creators returned
  }),
});

const { scan_id, credits_reserved, typical_settle } = await res.json();
// credits_reserved is the worst case; typical_settle is what it usually costs.
// Poll GET /api/scans/${scan_id} until status === "succeeded".

Billing

· 1 credit per upstream request
· Private accounts skipped, at no cost
· Filtering and re-filtering are free
· Reserve settles down to actual, refunded pool-exact
· A scan that finds nothing refunds in full

When the upstream is down

A circuit breaker refuses new scans with 503 and a Retry-After header before any credits are reserved, rather than taking the money and failing. Service resumes on its own once the upstream recovers — no deploy, no manual step.

Limits

· Followers per scan: 200,000
· Concurrent scans: 5 per account
· Results page size: 100 (offset paging)
· Export: unlimited rows, streamed