# API FAQ

Short answers, with links to the reference. Pricing detail is in [Usage, pricing, and limits](/guides/usage-limits); status codes are in [Error handling](/guides/error-handling).

## Getting started

### Who is the API for?

Developers building integrations, and the operations and commercial teams who use those integrations for creator sourcing and enrichment.

### Which plans include API access?

API access is available on the **Pro** plan.

Trial accounts get **30 successful API requests**. Requests that return an error do not count.

### How do credits work?

Credits are deducted only when a request returns data. A request that returns no results deducts nothing.

div
[Calculate Credits](/guides/usage-limits#credit-calculator)

### Are credits deducted for repeated requests with the same filters?

Yes. Every request that returns data deducts credits, regardless of whether the filters or parameters match a previous request.

## Authentication

### How do I authenticate?

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

```
Authorization: Bearer YOUR_API_KEY
```

Create and manage API keys in the [dashboard](https://dashboard.influencers.club/api).

### API key or OAuth — which should I use?

- **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.

### Can I see an API key again after creating it?

Yes. You can view an existing key again in the [dashboard](https://dashboard.influencers.club/api). Treat keys as long-lived secrets and revoke any key you no longer use.

### How do I revoke or rotate a key?

Revoke a key from the [dashboard](https://dashboard.influencers.club/api) — it stops working immediately. To rotate without downtime, create a new key, switch your integration over to it, then revoke the old one.

## Limits & pagination

### What are the rate limits?

The API is rate limited to **300 requests per minute**.

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

### What is the maximum value for `limit`?

- **Discovery endpoints** — maximum `limit` is **200** per request. They paginate with `page`, which is zero-indexed; see [How does pagination work?](#how-does-pagination-work) below.
- **Classifier endpoints** — maximum `limit` is **100** per request. They paginate with `offset` instead of `page`.


Each request returns one page only.

### How does pagination work?

Pagination is page-based and **zero-indexed**:

- `page=0` returns the first page of results (up to `limit` results)
- `page=1` 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:

```json
"paging": {
  "limit": 50,
  "page": 1
}
```

That object returns page 1 only — the second page, up to 50 results.

## Discovery

### Does the Discovery API return emails?

No. Discovery returns creator profile data only.

To retrieve verified email addresses, call [Enrich by handle (Profile)](/openapi/enrich-by-handle-profile) after Discovery — it returns the same validated email as the Full tier for 0.2 credits instead of 1. Use [Enrich by handle (Full)](/openapi/enrich-by-handle-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)


### Is there a limit on how many creators I can discover?

Yes. Discovery has a fair-use cap on unique creators returned. Every renewal raises it, and anything you do not use carries over. Canceling your subscription clears it. The cap scales with your plan and billing cycle (annual plans include more), and you can ask us to raise it.

Within a billing period the same creator counts only once, however often you return them, and your team shares one cap. We email your account owner as you approach it. Discovery pauses and returns `429` until your subscription renews. Check your current cap in the [dashboard](https://dashboard.influencers.club/api).

See [Usage, pricing, and limits](/guides/usage-limits#discovery-fair-use-cap) for full detail.

### Can I see which filter values each creator matched?

Yes. Add `return_filter_values=true` as a query parameter on a [Discovery API](/openapi/discovery-api/public_v1_discovery_create) request — it goes on the URL, not in the request body like the filters:

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

Each returned creator then includes a `matched_filters` object showing which of your filters it matched. Numeric filters — posting frequency, growth, income, and the per-platform metrics — come back as the creator's actual value, not the threshold you sent:

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

The full field-by-field shape is in the `matched_filters` schema on the [Discovery API reference](/openapi/discovery-api/public_v1_discovery_create).

Calls with `return_filter_values=true` are billed at **0.03 credits per creator** instead of the standard 0.01 — the premium rate replaces the base rate; it is not added to it. Premium pricing does not change how the Discovery fair-use cap is counted.

### Can I search in plain English instead of building filters?

Yes. Send an `nlp_search` brief at the top level of a [Discovery API](/openapi/discovery-api/public_v1_discovery_create) request and the AI turns it into filters before the search runs:

```json
{
  "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).

NLP searches are billed at the normal Discovery rate. If the brief is too vague to produce filters, the request returns `400` and nothing is charged.

## Enrichment

### Which Enrich by handle tier should I use?

Four tiers return different slices of the same source. Pick the cheapest one that covers what you need:

| Tier | Credits | What you get |
|  --- | --- | --- |
| [Raw](/openapi/enrich-by-handle-raw) | 0.03 | Unprocessed platform data straight from the source — basic profile info, post data, media counts, platform-native metadata. |
| [Profile](/openapi/enrich-by-handle-profile) | 0.2 | Identity, contact and vetting — validated email, name, gender, location, cross-platform presence, verification, account type, follower/media counts, bio, niche. |
| [Analytics](/openapi/enrich-by-handle-analytics) | 0.8 | Performance only — engagement and growth detail, posting frequency, medians, income estimates, audience data, optional lookalike creators. |
| [Full](/openapi/enrich-by-handle-full) | 1 | Everything in Profile and Analytics, plus `post_data`. |


Profile and Analytics together cost the same as one Full call. Full also returns `post_data`, which neither tier includes; Raw returns it too, at 0.03, if raw post data is all you need. Analytics is available for Instagram, YouTube, TikTok, OnlyFans, Twitter and Twitch.

### How does batch enrichment work?

Batch enrichment handles a whole list in one job. Two steps:

1. Upload a CSV (up to **10,000 contacts** per batch) — creating the batch starts it; there is no separate start step
2. Poll the status endpoint, then download the enriched CSV output


If a batch pauses because you run out of credits, top up and resume it within **7 days** — processing continues from where it stopped. After 7 days the batch is marked finished and the partial results stay available to download.

Use batch for any list you would otherwise loop over one request at a time.

## Data & responses

### Does the API return profile images?

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

Some picture URLs are **signed and expire after 24 hours** — download and store the image within that window. Others point at the platform's own CDN and may expire without notice.

### Why are engagement metrics sometimes 0, null, or missing?

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


A metric the platform does not expose comes back as 0 or null.

## Workflows

### What is the recommended approach for large sourcing runs?

Order of operations:

1. Use Discovery with `page` and `limit` to build your candidate list.
2. Call Enrich by handle (Profile) on the subset you need contact data for, or (Full) if you also need analytics.
3. Use batch enrichment for very large lists (up to 10,000 at a time).


## Support

Questions or problems: open the chat widget at the bottom right of any page.