API reference

JSON in, JSON out, one key. Base URL: https://app.voxelised.com/v1

Authentication

Every request carries your API key in the Authorization header. Your key is on your dashboard. Keep it on your server: anyone holding it can spend your credits.

Authorization: Bearer vox_live_YOUR_KEY

Credits

Each lookup reserves its credits, runs, and keeps them only if it found something. A miss, a timeout or an error gives them back at once. Every reply says what it charged and what’s left, and the X-Credits-Left header carries the balance too.

Up to 60 lookups a minute per account. Social analysis can take a few seconds; allow up to 60 seconds before timing out.

Responses

Every lookup answers with the same envelope. status is found or not_found; result is null when nothing was found.

{
  "request_id": "req_…",
  "status": "found",
  "result": {
    "…": "the lookup's fields"
  },
  "credits": {
    "charged": 0.75,
    "left": 99.25
  }
}

Find a work email

POST /v1/email

A person's work email from their name and company domain, or from their LinkedIn profile. Add verify to check it's deliverable.

Body

Field	Type	Required	What it is
full_name	string	or first + last	The person's name.
first_name, last_name	string	no	Instead of full_name.
domain	string	with a name	The company website, like northwind.dev.
linkedin_url	string	or name + domain	Their LinkedIn profile link.
verify	boolean	no	Also check the email is deliverable (1 more credit).

Request

curl https://app.voxelised.com/v1/email \
  -H "Authorization: Bearer vox_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Ada Lovelace","domain":"northwind.dev","verify":true}'

Response

{
  "request_id": "req_6f1c…",
  "status": "found",
  "result": {
    "email": "ada@northwind.dev",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "verification": {
      "status": "valid"
    }
  },
  "credits": {
    "charged": 2,
    "left": 98
  }
}

0.75 credits when found, plus 1.25 when the check runs. Nothing when it isn't found.

Find a phone number

POST /v1/phone

A direct or mobile number from a LinkedIn profile, a work email, or a name and company domain.

Body

Field	Type	Required	What it is
linkedin_url	string	one of these	Their LinkedIn profile link (the best input).
email	string	one of these	Their work email.
full_name + domain	string	one of these	Their name and company website.

Request

curl https://app.voxelised.com/v1/phone \
  -H "Authorization: Bearer vox_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url":"https://www.linkedin.com/in/ada-northwind"}'

Response

{
  "request_id": "req_91ab…",
  "status": "found",
  "result": {
    "phone": "+14155550142",
    "type": "mobile"
  },
  "credits": {
    "charged": 4,
    "left": 94
  }
}

4 credits when a number is found. Nothing when it isn't.

Get a LinkedIn profile

POST /v1/linkedin

The full public profile: headline, location, current roles, work history with dates, education, skills and languages.

Body

Field	Type	Required	What it is
url	string	yes	A LinkedIn profile link, or just the name in it (linkedin.com/in/name).

Request

curl https://app.voxelised.com/v1/linkedin \
  -H "Authorization: Bearer vox_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.linkedin.com/in/ada-northwind"}'

Response

{
  "request_id": "req_2d7e…",
  "status": "found",
  "result": {
    "profile": {
      "name": "Ada Lovelace",
      "headline": "VP Engineering, Northwind",
      "location": "London",
      "current_roles": [
        {
          "title": "VP Engineering",
          "company": "Northwind",
          "duration": "3 yrs 2 mos"
        }
      ],
      "experience": [
        "…"
      ],
      "education": [
        "…"
      ],
      "skills": [
        "Distributed systems"
      ],
      "followers": 4120
    }
  },
  "credits": {
    "charged": 0.75,
    "left": 93.25
  }
}

0.75 credits when the profile is found. Nothing when it isn't.

Analyse a social account

POST /v1/social

What works on a TikTok, Instagram, YouTube or LinkedIn account: reach, cadence, engagement, top posts, the formats, lengths, days and hashtags that do best, and plain-English insights.

Body

Field	Type	Required	What it is
platform	string	yes	tiktok, instagram, youtube or linkedin.
handle	string	yes	The account name or a link to it (@name, a channel link, a LinkedIn profile).

Request

curl https://app.voxelised.com/v1/social \
  -H "Authorization: Bearer vox_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"tiktok","handle":"@northwind"}'

Response

{
  "request_id": "req_c40f…",
  "status": "found",
  "result": {
    "platform": "tiktok",
    "account": {
      "handle": "northwind",
      "followers": 182000
    },
    "window": {
      "posts_analyzed": 20,
      "from": "2026-10-02",
      "to": "2026-10-23"
    },
    "summary": {
      "posts_per_week": 4.5,
      "typical_views": 48200,
      "engagement_rate_pct": 1.9
    },
    "top_posts": [
      "…"
    ],
    "patterns": {
      "by_length": [
        "…"
      ],
      "best_weekday": {
        "label": "Thursday",
        "posts": 4,
        "vs_overall": 1.6
      }
    },
    "insights": [
      "Videos under 15s do best: 2.1x the typical views (9 posts)."
    ]
  },
  "credits": {
    "charged": 2,
    "left": 91.25
  }
}

2 credits when the account is found. Nothing when it isn't.

Growth playbook

For AI agents onlyPOST /v1/playbook

Research for an agent writing a growth plan: what’s working right now in a niche on TikTok, Instagram, YouTube Shorts or LinkedIn, every post measured against its own account’s normal, with the winners, flukes and ordinary posts, the accounts read, measured patterns with a chance check, and transcripts of the top winners.

How a run goes

Call	What it does
POST /v1/playbook	Starts the research and answers at once: `202` with a `check` link. A brief with parts missing answers `needs_input` with the questions to ask, free.
GET /v1/playbook/{id}	`running` (with progress) until `done`, usually 1 to 4 minutes. Add `?platform=tiktok` for one platform.
POST /v1/playbook/{id}/compare	The agent’s labels for the posts in each `label_sheet`; answers winners against ordinary posts per label, the lift, how many accounts won with it, and the chance check. Free.
GET /v1/playbook	The guide for agents, with the interview questions. No key needed.

Body

Field	Type	Required	What it is
brief.niche, brief.audience, brief.goal	string	yes	From the agent’s interview, in the person’s words.
brief.business, region, language, can_make, avoid, posts_per_week	string, list, number	no	Context for the agent’s briefs and roadmap; returned as sent.
platforms	list	yes	Any of tiktok, instagram, youtube, linkedin.
keywords	list	3 to 12	Search phrases the audience would use, in the content’s language.
handles	object	no	The person’s own account per platform: read in full for their baseline.
competitors	object	no	Up to 3 accounts per platform, each read in full.
window_days, max_length_s	number	no	How recent (14 to 90 days, 60 by default) and how long a short-form video may be (10 to 180 s, 90 by default).

Request

{
  "brief": {
    "business": "A men's skincare brand selling a three-step kit online",
    "niche": "skincare for men over 30",
    "audience": "Men 30 to 45 in the US who have never had a routine and feel their skin is ageing",
    "goal": "sales: 300 kit orders from social in 90 days",
    "region": "US",
    "language": "English",
    "can_make": [
      "talking to camera",
      "voice-over",
      "product close-ups"
    ],
    "avoid": [
      "dancing"
    ],
    "posts_per_week": 4
  },
  "platforms": [
    "tiktok",
    "instagram"
  ],
  "keywords": [
    "mens skincare routine",
    "skincare for men",
    "razor bumps",
    "skincare myths",
    "anti aging men",
    "skincare"
  ],
  "handles": {
    "instagram": "@yourbrand"
  },
  "competitors": {
    "tiktok": [
      "@a_competitor"
    ]
  }
}

# Start the research (answers at once with a check link)
curl https://app.voxelised.com/v1/playbook \
  -H "Authorization: Bearer vox_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

# Then, every 20 seconds until status is "done"
curl https://app.voxelised.com/v1/playbook/pb_YOUR_ID \
  -H "Authorization: Bearer vox_live_YOUR_KEY"

Response

{
  "playbook_id": "pb_7c1e…",
  "status": "done",
  "platforms": {
    "tiktok": {
      "enough_evidence": true,
      "measure": "views",
      "studied": {
        "in_window": 312,
        "with_normal": 214,
        "accounts_read": 14,
        "winners": 31,
        "flukes": 6,
        "ordinary": 44
      },
      "base_rate_pct": 17,
      "normals": {
        "median": 41200,
        "by_size": [
          {
            "followers": "under 10k",
            "accounts": 3,
            "median_normal": 1300
          }
        ]
      },
      "posts": [
        {
          "id": "7698…",
          "url": "https://www.tiktok.com/@…/video/7698…",
          "group": "winner",
          "multiple": 12.4,
          "normal": 4100,
          "views": 50840,
          "per_day": 3631,
          "duration_s": 14,
          "title": "…"
        }
      ],
      "label_sheet": [
        {
          "id": "7698…",
          "url": "…",
          "caption": "…",
          "transcript": "…",
          "transcript_checked": true
        }
      ],
      "patterns": [
        {
          "feature": "length",
          "rows": [
            {
              "value": "15 s or less",
              "winners": {
                "n": 14,
                "of": 31,
                "pct": 45
              },
              "ordinary": {
                "n": 9,
                "of": 44,
                "pct": 20
              },
              "lift": 2.2,
              "p": 0.024,
              "read": "winners do this more, past chance",
              "examples": [
                "7698…"
              ]
            }
          ]
        }
      ],
      "own": {
        "handle": "yourbrand",
        "found": true,
        "analysis": {
          "…": "the social analysis"
        }
      }
    }
  },
  "credits": {
    "charged": 30,
    "left": 70
  }
}

15 credits per platform, reserved when the run starts and kept only for platforms with enough to go on (15 or more recent posts with a known normal, from 4 or more accounts). A needs_input answer, a run that doesn’t finish and compare are free. Two runs at a time per account.

Account and balance

GET /v1/me

Who the key belongs to, the credits left, and what each of your services costs. Free.

curl https://app.voxelised.com/v1/me \
  -H "Authorization: Bearer vox_live_YOUR_KEY"

Errors

Errors answer with { "error": { "code", "message" } }. A failed lookup is never charged.

Code	Status	What to do
invalid_request	400	The body is missing something or has a field we don't know. The message says what to send.
missing_api_key / invalid_api_key	401	Send Authorization: Bearer vox_live_… with the key from your dashboard.
insufficient_credits	402	Not enough credits for this lookup. Nothing was charged.
account_pending / account_paused / service_not_enabled	403	The account isn't active yet, or this service isn't on for it.
rate_limited	429	More than the per-minute limit. Slow down and retry.
account_daily_limit	429	Today's limit on lookups that find nothing is used up. It resets at 00:00 UTC.
lookup_failed	502	The lookup didn't complete. Nothing was charged; retry.
temporarily_unavailable / daily_cap_reached	503	Briefly unavailable. Nothing was charged; retry later.