API FAQ

This page answers common questions about API access, credits, pagination, enrichment, performance, and metric behavior.

The API is designed for developers integrating programmatically, as well as operations and commercial teams running creator sourcing and enrichment workflows.

API access is available to Pro subscribers.

Trial accounts can test the API with 10 trial credits.

Credits are deducted only when a request successfully returns data. No credits are deducted when a request returns no results.

Yes. Every request that returns data deducts credits, regardless of whether the filters or parameters match a previous request. The API fetches fresh, up-to-date data on each call.

It is the client's responsibility to monitor request volume and credit usage. Use the dashboard or GET /public/v1/account/credits to track remaining credits.

Every request must include your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create and manage your keys in the dashboard.

• API key — for your own scripts, backend services, and integrations, where you call the API as yourself. Most integrations use this.
• OAuth — for building an application that other Influencers Club users authorize to act on their behalf (for example a desktop or CLI tool). Your app obtains tokens through the OAuth flow rather than using a static key.

If you're integrating for your own account, use an API key.

Yes. Your active keys, including their values, stay available at any time — from the dashboard and the list endpoint, not only at creation. Treat them as long-lived secrets and revoke any key you no longer use.

Revoke a key from the dashboard — it stops working immediately. To rotate without downtime, create a new key, switch your integration over to it, then revoke the old one.

The API is limited to 300 requests per minute per account.

If you paginate large result sets, implement request throttling and backoff to stay within the limit.

• Maximum limit: 50 results per page.

Each request returns one page only.

If you want 150 results with limit=50, you must make 3 requests:

• page 1
• page 2
• page 3

Pagination is page-based:

• page=1 returns the first page of results (up to limit results)
• page=2 returns the second page of results (up to limit results), and so on

If you need results across multiple pages, you must request each page separately.

Example paging object:

"paging": {
  "limit": 50,
  "page": 3
}

The example above returns only page 3 (up to 50 results).

No. Discovery returns creator profile data only.

To retrieve verified email addresses, use Enrich by Handle – Profile after Discovery — it returns the same validated email as Full for 0.2 credits instead of 1. Use Full only if you also need performance analytics in the same call.

Typical workflow:

1. Discovery → collect handles
2. Enrich by Handle → retrieve detailed data (and email where available)

Yes. Each billing period you can discover a capped number of unique creators. The allowance scales with your plan and billing cycle (annual plans include more), and approved accounts can have it raised after review.

The same creator only counts once per period, and team members share one cap. When you reach the cap, discovery returns 429 and stays blocked until your subscription renews. Check your current allowance in the dashboard.

See Usage & limits for full detail.

Yes. Add return_filter_values=true as a query parameter on a Discovery API request — it goes on the URL, not in the request body like the filters:

POST https://api-dashboard.influencers.club/public/v1/discovery/?return_filter_values=true

Each returned creator then includes a matched_filters object showing exactly which of your filter values it matched — useful for scoring results, attributing matches, or building a "why this creator" view in your own app:

{
  "user_id": "17841400000000000",
  "profile": { "username": "examplecreator", "...": "..." },
  "matched_filters": {
    "audience_location": ["US>30%"],
    "audience_gender": "female>60%",
    "creator_has": { "has_tiktok": true },
    "hashtags": ["skincare"]
  }
}

Audience conditions come back as "<value>>NN%" strings, presence flags (creator_has, has_brand_deals, …) as booleans, and hashtags/topics as the values you searched. The full field-by-field shape is in the matched_filters schema on the Discovery API reference.

This is a premium option: calls with return_filter_values=true are billed at 0.03 credits per creator instead of the standard 0.01 (this replaces the base rate, it is not additive). The unique-creator cap is unchanged.

Yes. Send an nlp_search brief at the top level of a Discovery API request and the AI turns it into filters before the search runs:

{
  "platform": "instagram",
  "nlp_search": "fitness creators in New York with over 100k followers",
  "paging": { "limit": 10, "page": 0 }
}

You can mix it with normal filters. Anything you set yourself wins — the AI only fills in what you left out, and it never changes the platform you sent.

The response tells you what actually happened: applied_filters is the filter set the search ran with, and nlp_search contains from_nlp (what the AI inferred), overridden_by_user (where your value beat the AI's), and notes (why anything was dropped, for example a filter unavailable on that platform).

Briefs are billed at the normal Discovery rate. If a brief is too vague to become filters you get a 400 and nothing is charged, rather than an unconstrained search you'd pay for.

Four tiers return progressively more data from the same source. Pick the cheapest one that covers what you need:

Profile and Analytics are complementary halves of Full, so if you need both it costs the same as calling Full once. Analytics is only available for Instagram, YouTube, TikTok, OnlyFans, Twitter and Twitch — the other platforms have no performance data.

Enrich by Handle – Profile and Full return only valid email addresses when available. Emails are validated via a third-party verification provider before inclusion.

Batch enrichment is designed for scale.

You can:

1. Upload a CSV (up to 10,000 contacts)
2. Start the batch job
3. Download the enriched CSV output

Batch is recommended for large lists where you prefer asynchronous processing over making many individual requests.

Yes. Profile picture URLs are included in responses where available.

All profile pictures are stored on our infrastructure and returned at the highest resolution available. The URLs are signed and expire after 24 hours — this is a security measure and recommended industry practice. Download and store the images on your side within that window.

This most commonly happens when:

• the creator hides likes/views/comments
• the platform restricts metric visibility
• the metric is unavailable for the requested timeframe or content type

When a platform does not expose a metric, it cannot be reliably returned, and the value may appear as 0 or null.

For large sourcing workflows:

1. Use Discovery with clear sorting and paging.
2. Paginate programmatically until you reach your target volume.
3. Use Enrich by Handle – Full for the subset you need contact and analytics data.
4. Use Batch Enrichment for very large lists (up to 10,000 at a time).

For any issues or questions please contact aleksandra@influencers.club.