Skip to main content
Version: beta-v1

Toksta Partner API

Private beta API for searching, enriching, and evaluating LinkedIn creators in Toksta.

Authentication uses manually issued partner API keys in the Authorization header: Bearer tk_live_your_api_key_here

Private Beta​

The Partner API is currently in private beta.

Access is not self-serve yet. If you want to use the API, you need to request access from the Toksta team so we can:

  • confirm your use case
  • provision a partner account
  • issue a dedicated API key
  • set your per-partner pricing and rate limits

If you want access, contact your Toksta account manager or the Toksta team directly and ask for Partner API beta access.

What This API Is For​

The Partner API is designed for server-to-server integrations that need structured creator discovery workflows without using the Toksta app manually.

Typical use cases include:

  • searching the Toksta LinkedIn creator database
  • running keyword-driven discovery search
  • retrieving full creator records
  • requesting fresh enrichment data
  • running async content or audience matching jobs
  • generating curated thought-leader shortlists
  • checking monthly usage and billing totals

How Access Works​

You authenticate with a manually issued bearer token:

Authorization: Bearer tk_live_your_api_key_here

Keys are issued per partner account. They should be used from your backend only, not embedded in browser-based applications.

Each partner account can have:

  • its own API key or keys
  • its own rate limit
  • its own per-operation pricing
  • its own included credit allocation and credit enforcement settings

Sync vs Async Endpoints​

Some endpoints return immediately, while others start a background job and return a job_id.

Use immediate endpoints when you want:

  • normal search results
  • creator detail
  • current usage totals

Use async endpoints when Toksta needs to do heavier work such as:

  • refreshing enrichment data
  • analyzing recent post content
  • analyzing audience fit
  • building a ranked thought-leader shortlist

For async workflows, the pattern is:

  1. POST the request
  2. receive a job_id
  3. poll GET /v1/jobs/{id} until the status is completed, partial, or failed

Thought Leaders Modes​

POST /v1/creators/thought-leaders supports three operating modes:

  • broad: fastest path for niche discovery. It uses the widest candidate pool and the lightest gating, so it tends to return more results in narrower categories.
  • balanced: middle-ground mode when you want decent recall without going fully broad.
  • strict: strongest quality gating. This is the best fit for mainstream niches where you care most about follower size, recent engagement, and content relevance.

The endpoint now treats count as the target number of thought leaders to return. Toksta keeps searching in batches until it reaches that target, exhausts the ranked candidate pool, or hits the configured analysis budget.

Thought leader jobs also require at least 5 keywords. Toksta expands those keywords internally to improve recall, but you should still provide a reasonably rich keyword set up front.

Understanding The Metrics​

Most creator responses include a metrics object. These are designed to help you rank and filter creators consistently.

The most important fields are:

  • followers_count: the creator's follower count on LinkedIn
  • engagement_rate: a summary engagement percentage for recent content
  • avg_posts_per_month: median posting frequency across recent activity, despite the legacy field name
  • reactions_per_post: median reactions on recent posts
  • comments_per_post: median comments on recent posts
  • shares_per_post: median repost/share activity on recent posts

The CreatorSummary.metrics field names are legacy API names, but in practice these per-post activity values are intended to represent median recent performance rather than simple arithmetic averages. This gives a more stable view of creator quality and is less distorted by a single viral post.

Enriched responses may also include explicit median-based metrics such as median_reactions_per_post, median_comments_per_post, and median_shares_per_post.

Why Some Endpoints Return 404 And Others Do Not​

Not every endpoint treats "no matches" as an error.

  • Search-style endpoints such as POST /v1/creators/search, POST /v1/creators/discovery-search, and POST /v1/creators/thought-leaders are discovery workflows. If nothing matches, Toksta returns a successful response with an empty result set or an async job that completes with empty results.
  • ID-based endpoints such as GET /v1/creators/{id} and GET /v1/jobs/{id} return 404 when the referenced resource does not exist for your partner account.
  • Bulk analysis endpoints such as enrichment, content match, and audience match can return 404 when none of the supplied creator IDs resolve to valid LinkedIn creators in Toksta.

Thought leader responses add relevance metrics such as:

  • score: Toksta's overall ranking score for the shortlist
  • match_rank: backward-compatible alias of score
  • content_match_score: how strongly recent post content aligns with the requested topic
  • matching_posts: how many analyzed posts were judged relevant
  • posts_analyzed: how many recent posts were checked

Thought leader job responses also include workflow metadata such as:

  • requested_count: the target shortlist size requested in the original job
  • returned_count: the number of creators actually returned
  • analyzed_creators: the number of creators Toksta had to inspect and score
  • search_exhausted: whether Toksta ran out of viable ranked candidates before reaching the requested count
  • max_candidates_to_analyze: the search budget that capped the job

Billing And Usage​

Billing is tracked by operation type and can vary by partner account.

In practice, that means:

  • one partner can have different pricing than another
  • some operations can be free for one partner and paid for another
  • monthly totals are calculated from actual logged usage
  • a partner account can be provisioned with a credit balance for beta testing or prepaid usage

Current beta integrations typically use:

  • 1 credit = $0.01
  • enrich: 2 credits per request
  • content_match: 2 credits per request
  • audience_match: 2 credits per request
  • thought_leaders_broad: 2 credits per analyzed creator
  • thought_leaders_balanced: 3 credits per analyzed creator
  • thought_leaders_strict: 4 credits per analyzed creator
  • search, profile_read, job_status, and account_usage: free

For thought leaders, Toksta reserves credits before the job starts and then settles the final charge based on the actual number of creators analyzed. Any unused reserved credits are released back to the partner account.

You can retrieve your usage summary from GET /v1/account/usage.

The usage response includes both monthly billing totals and the current credit state for the authenticated account, including:

  • allocated_credits
  • remaining_credits
  • credit_value_usd
  • enforce_credit_limits

When credit enforcement is enabled and a billable request would exceed the remaining balance, Toksta returns 402 CREDIT_LIMIT_EXCEEDED instead of starting the job.

Getting Started​

For most integrations, the recommended first flow is:

  1. request Partner API beta access and receive your API key
  2. call POST /v1/creators/search or POST /v1/creators/discovery-search
  3. fetch a full profile with GET /v1/creators/{id} when needed
  4. use async jobs for enrichment, content match, audience match, or thought leaders
  5. monitor job completion with GET /v1/jobs/{id}
  6. review current monthly usage and remaining credits with GET /v1/account/usage

Authentication​

Partner API key in the form tk_live_... or tk_test_....

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

API key