# Core API Concepts

**Discovery**

Identify and evaluate creators using structured, platform-specific search criteria.
Responses are intentionally constrained to support ranking, filtering, and selection
at scale rather than full profile hydration.

**Enrichment**

Retrieve complete creator-level data once a candidate has been identified.
Enrichment responses provide the depth required for analysis, activation,
and downstream data workflows.

**Execution modes**

Enrichment is available in both synchronous and asynchronous forms.
Single enrichment supports real-time use cases, while batch enrichment is optimized
for high-throughput, non-interactive processing.

**Typical usage**

Discovery and enrichment are designed as complementary stages.
Discovery narrows the candidate set; enrichment supplies detailed data
for creators that have already been qualified.


Version: 1.0.0

## Servers

Production
```
https://api-dashboard.influencers.club
```

## Security

### Bearer

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Core API Concepts](https://docs.influencers.club/_bundle/openapi.yaml)

## Discovery API

### Discovery API

 - [POST /public/v1/discovery/](https://docs.influencers.club/openapi/discovery-api/public_v1_discovery_create.md): Search and discover creators across multiple platforms using advanced filtering and search.

Platform-specific filters
- The available filters depend on the platform you choose.
- When you switch platform, you’ll see different filter fields available in the request body for that platform.
- Use the Dictionary endpoints to retrieve valid values for filters such as locations, languages, brands, audience interests, and audience locations.

Credits
- 0.01 credits per creator returned. If a request returns 0 creators, 0 credits are deducted.
- Credits are consumed on every request that returns creators, even if the filters are identical to a previous request.It is the client's responsibility to monitor request volume and credit usage.

Limits
- Up to 10,000 relevant results can be fetched by each query. Fetching data after the 10,000th result is not allowed.
- Each account has a separate Discovery API credit limit equal to 10% of the plan's total credits, which resets each billing cycle. See the FAQ for details.

What you get
- Paginated list of creator profiles with profile info, follower counts, engagement rates, and analytics. Instagram creators (10k+ followers) also include audience demographics and interest data.
- Supports Instagram, YouTube, TikTok, Twitch, Twitter, and OnlyFans platforms.

## Similar Creators

### Similar Creators

 - [POST /public/v1/discovery/creators/similar/](https://docs.influencers.club/openapi/similar-creators/public_v1_discovery_creators_similar_create.md): Discover creators similar to a reference creator based on various similarity criteria.

What you get
- Returns a paginated list of creator profiles that match the reference creator's characteristics, content style, audience, or other specified attributes.
- Supports filtering by URL, username, or ID, and allows additional filters to refine similarity matching.
- Useful for finding lookalike creators, competitors, or creators in the same niche.

Credits
- 0.01 credits per creator returned. If no creators are returned, no credits are deducted.
- Credits are consumed on every request that returns creators, even if the filters are identical to a previous request.
- It is the client's responsibility to monitor request volume and credit usage.

Limits
- Up to 10,000 relevant results can be fetched by each query. Fetching data after the 10,000th result is not allowed.

## Audience Overlap

### Audience Overlap

 - [POST /public/v1/creators/audience/overlap/](https://docs.influencers.club/openapi/audience-overlap/public_v1_creators_audience_overlap_create.md): Compare audience overlap between 2-10 creators on a given platform.

What you get
- Returns per-creator audience overlap and unique audience percentages, plus report-level totals (total followers and total unique followers across all compared creators).
- Useful for evaluating creator partnerships, identifying audience duplication across campaigns, and optimizing influencer selection for maximum reach.

Credits
- 1 credit per request, regardless of how many creators are compared.

## Dictionary

Provides the complete set of supported filter values used by the Discovery and Similar Creators endpoints.

These endpoints return all valid, platform-specific values (such as languages, locations, brands, YouTube topics, Twitch games, audience brand categories, audience brand names, audience interests, and audience locations) that can be used when constructing discovery queries.

Clients should retrieve dictionary values programmatically to ensure only supported values are sent in requests. Available values may vary by platform and can evolve over time.


### Languages

 - [GET /public/v1/discovery/classifier/languages/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_languages_list.md): Retrieve a list of supported languages with their abbreviations for filtering creators by profile language or content language. Useful for discovering creators who create content in specific languages or target particular linguistic audiences.

Credits
- 0 credits. This endpoint does not deduct credits.

### Platform Locations

 - [GET /public/v1/discovery/classifier/locations/{platform}/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_locations_retrieve.md): Retrieve a list of location identifiers available for a specific platform.

What you get
- Returns location strings that can be used to filter creators by geographic location in discovery searches.
- Platform-specific location data helps target creators from specific regions, cities, or countries.

Credits
- 0 credits. This endpoint does not deduct credits.

### Brands

 - [GET /public/v1/discovery/classifier/brands/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_brands_list.md): Retrieve a comprehensive list of brand names available for filtering in creator discovery searches. Returns brand identifiers including full names, cleaned names, and usernames that can be used to find creators who have worked with specific brands or mentioned them in their content.
Credits - 0 credits. This endpoint does not deduct credits.

### Youtube Topics

 - [GET /public/v1/discovery/classifier/yt-topics/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_yt_topics_list.md): Retrieve a hierarchical list of YouTube topic categories and their subtopics.

What you get
- Returns topic details and sub-topic details that can be used to discover YouTube creators who create content in specific categories or niches.
- Useful for finding creators in particular content verticals or subject areas.

Credits
- 0 credits. This endpoint does not deduct credits.

### Twitch Games

 - [GET /public/v1/discovery/classifier/games/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_games_list.md): Retrieve a list of video games available on Twitch that can be used for filtering creators. Returns game identifiers and metadata to help discover Twitch streamers who play specific games or have streamed particular titles.

Credits
- 0 credits. This endpoint does not deduct credits.

### Audience Brand Categories

 - [GET /public/v1/discovery/classifier/audience-brand-categories/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_brand_categories_list.md): Returns a list of audience brand categories (e.g., Sports, Fashion, Technology) from Instagram creator audience data. Use these values in the audience.brand_categories filter on the Discovery API to search for Instagram creators (10k+ followers) whose audience follows brands in specific categories.

Credits
- 0 credits. This endpoint does not deduct credits.

### Audience Brand Names

 - [GET /public/v1/discovery/classifier/audience-brand-names/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_brand_names_list.md): Returns a list of audience brand names (e.g., Nike, Apple, Starbucks) from Instagram creator audience data. Use these values in the audience.brands filter on the Discovery API to search for Instagram creators (10k+ followers) whose audience follows specific brands.

Credits
- 0 credits. This endpoint does not deduct credits.

### Audience Interests

 - [GET /public/v1/discovery/classifier/audience-interests/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_interests_list.md): Returns a list of audience interest values from Instagram creator audience data. Use these values in the audience.interests filter on the Discovery API to search for Instagram creators (10k+ followers) whose audience has specific interests.

Credits
- 0 credits. This endpoint does not deduct credits.

### Audience Locations

 - [GET /public/v1/discovery/classifier/audience-locations/](https://docs.influencers.club/openapi/dictionary/public_v1_discovery_classifier_audience_locations_list.md): Returns a list of audience location values (countries, states, cities) from Instagram creator audience data. Use these values in the audience.location filter on the Discovery API to search for Instagram creators (10k+ followers) whose audience is in specific locations.

Credits
- 0 credits. This endpoint does not deduct credits.

## Connected Socials

### Connected Socials

 - [POST /public/v1/creators/socials/](https://docs.influencers.club/openapi/connected-socials/public_v1_creators_socials_create.md): Discover all verified social accounts connected to a creator, given a seed platform and handle.

What you get
- Returns an array of verified connected social accounts across platforms, including platform name, username, and follower count for each connected account.
- Supports 11 seed platforms: Instagram, YouTube, TikTok, OnlyFans, Twitter, Snapchat, Discord, Pinterest, Facebook, LinkedIn, and Twitch.

Credits
- 0.5 credits per successful request. If no data is returned, no credits are deducted.

## Enrich by handle full

### Enrich by handle full

 - [POST /public/v1/creators/enrich/handle/full/](https://docs.influencers.club/openapi/enrich-by-handle-full/public_v1_creators_enrich_handle_full_create.md): Perform comprehensive enrichment of a creator profile using their social media handle.

What you get
- Returns complete profile data including cross-platform presence, engagement analytics, follower growth metrics, content performance data, monetization indicators, niche classification, hashtags, income estimates, and optional lookalike creator recommendations.
- Supports Instagram, YouTube, TikTok, OnlyFans, Twitter, Snapchat, Discord, Pinterest, Facebook, LinkedIn, and Twitch platforms.
- Optional email requirement and lookalike inclusion settings available.

Credits
- 1 credit per successful request. If no data is returned, no credits are deducted.

## Enrich by handle raw

### Enrich by handle raw

 - [POST /public/v1/creators/enrich/handle/raw/](https://docs.influencers.club/openapi/enrich-by-handle-raw/public_v1_creators_enrich_handle_raw_create.md): Retrieve raw platform data for a creator profile using their social media handle.

What you get
- Returns unprocessed platform-specific data directly from the source, including basic profile information, post data, media counts, and platform-native metadata.
- This endpoint provides the foundational data layer before any additional processing or enrichment.
- Supports Instagram, YouTube, TikTok, OnlyFans, Twitter, Snapchat, Discord, Pinterest, Facebook, and LinkedIn platforms.

Credits
- 0.03 credits per successful request. If no data is returned, no credits are deducted.

## Enrich by email advanced

### Enrich by email advanced

 - [POST /public/v1/creators/enrich/email/advanced/](https://docs.influencers.club/openapi/enrich-by-email-advanced/public_v1_creators_enrich_email_advanced_create.md): Perform comprehensive enrichment of creator profiles using an email address.

What you get
- Returns detailed cross-platform profile data including follower counts, engagement metrics, content analytics, monetization indicators, brand partnership history, and comprehensive social media presence across Instagram, YouTube, TikTok, Twitter, Twitch, OnlyFans, and LinkedIn.
- Supports filtering by minimum follower count and platform exclusions.

Credits
- 2 credits per successful request. If no data is returned, no credits are deducted.

## Enrich by email basic

### Enrich by email basic

 - [POST /public/v1/creators/enrich/email/](https://docs.influencers.club/openapi/enrich-by-email-basic/public_v1_creators_enrich_email_create.md): Perform basic enrichment of creator profiles using an email address.

What you get
- Returns essential profile information including basic social media presence, contact details, and platform account identifiers.
- Ideal for quick profile lookups and initial creator identification across Instagram, YouTube, TikTok, Twitter, Twitch, and OnlyFans.

Credits
- 0.1 credits per successful request. If no data is returned, no credits are deducted.

## Batch enrichment

Bulk enrichment jobs: create, check status, resume, and download results.

### Create Batch Enrichment

 - [POST /public/v1/enrichment/batch/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_create.md): Create a batch enrichment job by uploading a CSV.

How it works
1. Upload a .csv file (one column: handle or email)
2. Choose the enrichment mode (handle: raw/full, email: basic/advanced)
3. Use the returned batch_id to check status and download results

Request
- multipart/form-data
- file: CSV (max 10MB)
- Mode fields depend on whether you’re enriching by handle or email

Credits
- Credits are deducted per successfully enriched record
- The credit rate follows the corresponding single-enrichment mode (raw/full/basic/advanced)
- If no data is returned for a record, 0 credits are deducted for that record

Checking completion
Poll GET /public/v1/enrichment/batch/{batch_id}/status/ every 30–60 seconds until the job finishes. Status values:
- queued — waiting to start
- processing — actively enriching records
- finished — all records done; download results via GET /public/v1/enrichment/batch/{batch_id}/
- failed — job failed
- paused_insufficient_credits — top up credits and call the resume endpoint

This API is polling-based. There are no webhooks or push notifications.

### Download Batch Enrichment Results

 - [GET /public/v1/enrichment/batch/{batch_id}/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_retrieve.md): Download the final enriched dataset after processing is complete.

Requirements
- Batch must be in finished status
- Results file must have been generated

Output formats
- CSV (default) — omit format or pass ?format=csv
- JSON — pass ?format=json to receive a JSON array where each object has:
  - input_value — the original input (handle or email)
  - status — enrichment status for that record
  - enrichment_data — the enriched creator data

Error Responses
- 400 Bad Request — batch not completed yet or no results file available
- 404 Not Found — invalid batch ID or batch does not belong to client

Credits
- 0 credits (download only)

### Resume Batch Enrichment

 - [POST /public/v1/enrichment/batch/{batch_id}/resume/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_resume_create.md): Resume a paused or interrupted batch enrichment job.

When to use
- If a batch was paused or failed mid-run and needs to continue processing

Credits
- 0 credits to resume (credits apply only to successfully enriched records)

### Get Batch Enrichment Status

 - [GET /public/v1/enrichment/batch/{batch_id}/status/](https://docs.influencers.club/openapi/batch-enrichment/public_v1_enrichment_batch_status_retrieve.md): Check the current processing status of a batch enrichment job.

What you get
- Current state (e.g., queued/running/completed/failed)
- Progress indicators (processed vs remaining), when available

Credits
- 0 credits (status only)

## Creator Posts

### Creator Posts

 - [POST /public/v1/creators/content/posts/](https://docs.influencers.club/openapi/creator-posts/public_v1_creators_content_posts_create.md): Fetch recent posts for a creator on a given platform.

What you get
- Returns a list of recent posts with metadata including post ID, URL, caption, media URLs, timestamps, and engagement metrics (likes, comments, views, shares).
- Supports Instagram, TikTok, and YouTube platforms.
- Uses cursor-based pagination via next_token for fetching additional pages of results.
- Page sizes are platform-specific:
  Instagram — fixed at 12 posts per page (not configurable).
  TikTok — default 30, max 35.
  YouTube — default 30, max 50.

Credits
- 0.03 credits per successful request. If no data is returned, no credits are deducted.

## Post Details

### Post Details

 - [POST /public/v1/creators/content/details/](https://docs.influencers.club/openapi/post-details/public_v1_creators_content_details_create.md): Retrieve detailed information about specific creator content.

What you get
- Supports Instagram, TikTok, and YouTube platforms.
- Returns platform-specific content metadata and engagement data in a structured format.

Supported content types per platform
- Instagram: data, comments, transcript, audio
- TikTok: data, comments, transcript, audio
- YouTube: data, comments, transcript

Credits
- 0.03 credits per successful request. If no data is returned, no credits are deducted.

When to use
Use this endpoint when you have a specific post ID and need to go deeper than profile-level data. Typical use cases: brand safety review, transcript extraction for content analysis, pulling comment threads, and engagement deep-dives on individual posts.

Result format
The result field returns a platform-specific object:
- data — post metadata and engagement stats (likes, views, shares)
- comments — paginated comment list; use pagination_token to fetch the next page
- transcript — spoken text extracted from the video
- audio — audio resource reference (Instagram and TikTok only)

## Account credits & usage

Account-level endpoints (credits, usage).

### Check account credits and usage details

 - [GET /public/v1/accounts/credits/](https://docs.influencers.club/openapi/account-credits-and-usage/account_credits_usage_retrieve.md): Use your API key to check your remaining credits and total credits used.

Response fields
- credits_available — remaining credits
- credits_used — total credits consumed

Credits
- 0 credits