influData Social API Documentation

Overview

The Social API exposes influData's creator database — 90M+ profiles with audience demographics, performance metrics and content data — through a single REST interface. All endpoints return JSON, use the same authentication and share platform-agnostic response structures: an integration built for one platform works for all of them.

Base URL

https://app.infludata.com/api/externalAPI

Responses are gzip-compressed when the client sends Accept-Encoding: gzip. All timestamps are ISO 8601 in UTC.

Authentication

Every request is authenticated with a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

There are two kinds of keys:

Trial keys — self-serve, free, issued via createTrialKey + verifyTrialKey with email verification. 250 requests, valid 14 days.
Organization keys — for production use. Customers on plans with API access generate them in the influData app settings. Monthly request volumes depend on your plan.

Request budget & costs

Each key has a request budget (trial: total budget; production: monthly volume). Endpoints deduct from it as follows. Failed requests are not charged.

Endpoint	Cost
GET /getUserData	1 request — or 20 with includeAudienceReport=true
GET /discovery	1 request per search (20 results)
GET /getContent	1 request per content piece returned
GET /checkDataStatus	Free
POST /bulkAddToEnrich	Free
GET /getClientInfo	Free
GET /getCitiesForCountry	Free

Check your remaining balance anytime via getClientInfo— it's free.

Rate limits

Key type	Burst limit	Volume
Trial	2 req/s · 60 req/min	250 requests total, 14 days
Production	25 req/s · 1,000 req/min	Monthly request volume by plan

Exceeding a burst limit returns 429. Organization keys that exhaust their monthly volume also receive 429 with a resetDate field. Implement exponential backoff for retries.

Create trial key — step 1: request a verification code

POST/createTrialKey

Cost: Free, unauthenticated

Starts the self-serve trial signup. Runs abuse checks and emails a 6-digit verification code to the given address — the key itself is issued by verifyTrialKey. The code expires after 15 minutes; re-calling this endpoint sends a fresh code.

Body parameters (JSON)

Parameter	Type	Description
emailrequired	string	Your work email. Disposable email domains are rejected; one trial per inbox (plus-aliases count as the same inbox).
company	string	Optional company name (max 120 characters).

Example

curl -X POST "https://app.infludata.com/api/externalAPI/createTrialKey" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "company": "Your Company"}'

{
  "success": true,
  "message": "A 6-digit verification code was sent to you@company.com. ...",
  "nextStep": {
    "method": "POST",
    "url": "https://app.infludata.com/api/externalAPI/verifyTrialKey",
    "body": { "email": "you@company.com", "code": "<6-digit code from the email>" }
  },
  "codeExpiresInMinutes": 15
}

Response codes

200	Verification code sent.
400	Invalid or disposable email address.
409	A trial key was already issued for this email.
429	Per-IP or signup rate limit reached.
503	Global trial signup caps reached — retry later.

Verify trial key — step 2: exchange the code for your key

POST/verifyTrialKey

Cost: Free, unauthenticated

Validates the emailed code and returns your API key directly in the response (a copy is also emailed). Maximum 5 attempts per code.

Body parameters (JSON)

Parameter	Type	Description
emailrequired	string	The email used in step 1.
coderequired	string	The 6-digit code from the verification email.

Example

curl -X POST "https://app.infludata.com/api/externalAPI/verifyTrialKey" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "123456"}'

{
  "success": true,
  "apiKey": "your-trial-api-key",
  "clientId": "trial-aB3xK9pQz1",
  "expiresAt": "2026-06-25T00:00:00.000Z",
  "requestsIncluded": 250,
  "rateLimit": { "perSecond": 2, "perMinute": 60 },
  "baseUrl": "https://app.infludata.com/api/externalAPI",
  "quickstart": "curl -H \"Authorization: Bearer <apiKey>\" \"https://app.infludata.com/api/externalAPI/getUserData?platform=instagram&username=cristiano\""
}

Response codes

201	Key issued — returned in the response body.
400	Missing or malformed email/code.
401	Incorrect code (response includes attemptsRemaining).
404	No pending verification — request a code first.
410	Code expired — request a new one.
429	Too many incorrect attempts or verify rate limit reached.

Get creator profile

GET/getUserData

Cost: 1 request — 20 with includeAudienceReport=true

Returns a full creator profile: bio, follower/following counts, engagement metrics, verification status, demographics (country, language, gender, estimated age), growth timeline with collaboration mentions, and quality scores. With includeAudienceReport=true the response additionally includes audience demographics (age, gender, geo breakdown), interests and follower-quality metrics.

Parameters

Parameter	Type	Description
platformrequired	string	instagram, tiktok, youtube, twitch, facebook or snapchat.
username / userId / _idrequired	string	Exactly one identifier. username: platform handle (e.g. "adidas", "@MrBeast"). userId: platform-native ID (Instagram numeric ID, TikTok secUserId, YouTube channelId, Twitch ID). _id: influData internal ID — works without the platform parameter.
includeAudienceReport	boolean	true to include the full audience report (costs 20 requests). Available for Instagram, TikTok and YouTube. Default: false.
showDatalogAndScore	boolean	true to include profile scores and data logs (Instagram and TikTok). Default: false.

Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getUserData?platform=instagram&username=adidas&includeAudienceReport=true"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getUserData?platform=youtube&username=@MrBeast"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getUserData?_id=507f1f77bcf86cd799439011"

Response codes

200	Profile data returned.
201	Creator not in database yet — queued for enrichment, nothing charged. Retry within 24–48h.
202	Creator found but audience analysis still processing (1 request charged) — retry later.
400	Missing/invalid platform or identifier.
403	Insufficient request balance, or audience reports not enabled for this key.
404	Creator not found on the platform.
429	Monthly request limit exceeded (organization keys; includes resetDate).

Check data status

GET/checkDataStatus

Cost: Free

Returns metadata about a creator without consuming your budget: whether they exist in the database, data freshness, audience-report availability and timeline coverage. Also queues an instant data refresh, and optionally adds the creator to the weekly refresh schedule. Use it before getUserData to avoid spending requests on incomplete data.

Parameters

Parameter	Type	Description
platformrequired	string	instagram, tiktok, youtube or twitch.
username / userId / _idrequired	string	Exactly one identifier (same formats as getUserData).
addToWeeklyEnrichment	boolean	true to add the creator to the weekly refresh schedule. Not available for trial keys. Default: false.

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/checkDataStatus?platform=instagram&username=cristiano"

{
  "isInDatabase": true,
  "creatorId": "507f1f77bcf86cd799439011",
  "username": "cristiano",
  "platform": "instagram",
  "followers": 125000000,
  "lastRefreshDate": "2026-06-10T10:30:00Z",
  "lastAudienceDataRefresh": "2026-06-08T08:00:00Z",
  "hasAudienceData": true,
  "timelineDatapoints": 180,
  "isAddedToRefresh": true,
  "isAddedToWeeklyRefresh": false
}

Bulk enrichment

POST/bulkAddToEnrich

Cost: Free

Queues multiple creators for enrichment in one call — useful when onboarding creator lists. New creators are typically available within 24–48 hours.

Body parameters (JSON)

Parameter	Type	Description
platformrequired	string	instagram, tiktok, youtube or twitch.
usernames	string[]	Usernames to process (can be combined with userIds).
userIds	string[]	Platform-native user IDs to process.
addToWeeklyEnrichment	boolean	true to also add creators to the weekly refresh schedule (existing creators only). Not available for trial keys. Default: false.

Limits: maximum 100 items per request (usernames + userIds combined); 10 for trial keys.

Example

curl -X POST "https://app.infludata.com/api/externalAPI/bulkAddToEnrich" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram", "usernames": ["cristiano", "leomessi"], "addToWeeklyEnrichment": false}'

{
  "processed": [
    { "identifier": "cristiano", "type": "username", "isNewUser": false, "creatorId": "...", "addedToInstant": true, "addedToWeekly": false }
  ],
  "failed": [],
  "summary": { "total": 2, "existingInDatabase": 2, "newlyAdded": 0, "addedToInstant": 2, "addedToWeekly": 0, "failed": 0 }
}

Discovery search

GET/discovery

Cost: 1 request per search (20 results per page)

Search the creator database with filters for keywords, categories, location, language, audience size, engagement and growth. Returns 20 creators per page — paginate with skipCount (0, 20, 40, …). The response includes a total count and a relevance score (0–100) per result when keywords are used.

Parameters

Parameter	Type	Description
platformrequired	string	instagram, tiktok, youtube, twitch, facebook or snapchat.
skipCount	number	Pagination offset in increments of 20. Default: 0.
keywords	string	Comma-separated search terms. Terms with spaces are matched as exact phrases ("personal trainer"). Multiple terms are OR-combined.
keywordFields	string	Restrict keyword search to specific fields: bio, hashtags, content, website (comma-separated). Default: all fields. website is supported on Instagram, TikTok and YouTube.
categories	string	Comma-separated creator categories — see the categories reference below.
country	string	Creator country (full name, e.g. "Germany", "United States").
city	string	Creator city (combine with country; Instagram and TikTok). Valid values via getCitiesForCountry.
language	string	Creator language as 2-letter ISO code (e.g. en, de, fr).
gender	string	m (male) or w (female).
followerMin / followerMax	number	Follower/subscriber count range.
engagementRate	number	Minimum engagement rate (1 = 1%).
growthRate	number	Minimum monthly growth rate in percent.
viewsMin / viewsMax	number	Average views per post/video range (platform-dependent).
businessSearch	boolean	true to focus on business/brand accounts (Instagram).
sorting	string	Direction prefix + field: e.g. descFollowers, ascUsername. Fields: relevance, username, profileScore, followers, viewsPost, engagementMean, growthRate; plus totalViews (TikTok) and averageViewers (Twitch). Default: profile score.

Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/discovery?platform=instagram&country=Germany&followerMin=10000&categories=fitness"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/discovery?platform=tiktok&keywords=personal%20trainer,fitness%20coach&keywordFields=bio&sorting=descFollowers"

{
  "users": [
    {
      "_id": "profile_id_123",
      "username": "example_user",
      "displayName": "Example User",
      "followers": 125000,
      "platform": "instagram",
      "country": "Germany",
      "engagementMean": 4.2,
      "score": 95.8
    }
  ],
  "count": 1842,
  "dataSuccess": true
}

Get content

GET/getContent

Cost: 1 request per content piece returned

Query content pieces (posts, reels, stories, videos) with captions, hashtags, mentions, performance metrics and 24h-valid signed media URLs. Supports cursor-based pagination for large pulls and watermarks for incremental syncs.

Pagination parameters

Parameter	Type	Description
limit	number	Content pieces per page. Default and maximum: 100.
cursor	string	Opaque cursor from the previous response (next_cursor). Can also be sent via the X-Cursor header to avoid long URLs.
offset / skipCount	number	Legacy offset pagination — still supported, but cursor pagination is recommended.

Filter parameters

Parameter	Type	Description
platform	string	Comma-separated platforms. Default: instagram,tiktok.
username	string	Filter by creator username(s), comma-separated.
keywords	string	Comma-separated keywords searched in captions, hashtags and mentions. Phrases supported.
tags	string	Comma-separated hashtags (e.g. fashion,style).
min_followers / followerMin	number	Minimum creator follower count. Default: 10000.
followerMax	number	Maximum creator follower count.
viewsMin / viewsMax	number	Content reach/views range.
created_at_gte / uploadedFrom	string	Earliest upload date (ISO format).
created_at_lte / uploadedTo	string	Latest upload date (ISO format).
contentTypes	string	Comma-separated: post, reel, story (Instagram); video (TikTok/YouTube); short (YouTube).
country / city / gender / language	string	Creator demographics filters (gender: m or w; language: 2-letter code).
sorting	string	uploaded (default), reach or viral.

Example — cursor pagination

# First page
curl -H "Authorization: Bearer YOUR_API_KEY" -H "Accept-Encoding: gzip" \
  "https://app.infludata.com/api/externalAPI/getContent?platform=instagram,tiktok&tags=fashion,style&min_followers=10000&limit=100"

# Next page: pass next_cursor from the previous response
curl -H "Authorization: Bearer YOUR_API_KEY" -H "X-Cursor: eyJwaXRJZCI6..." \
  "https://app.infludata.com/api/externalAPI/getContent?limit=100"

{
  "items": [
    {
      "contentId": "IG_12345678901234567",
      "platform": "instagram",
      "contentType": "reel",
      "uploaded": "2026-05-15T10:30:00Z",
      "reach": 125000, "likes": 8500, "comments": 342,
      "engagementRate": 0.0745, "viralFactor": 1.23,
      "username": "fashioninfluencer", "followers": 45000,
      "captions": "Check out this amazing outfit! #fashion",
      "hashtags": ["fashion", "style"], "mentions": ["@brandname"],
      "imageUrl": "https://signed-url...", "videoUrl": "https://signed-url..."
    }
  ],
  "next_cursor": "eyJwaXRJZCI6...",
  "watermark": { "created_at_max": "2026-05-15T10:30:00Z", "last_id": "65abc123def456789" },
  "tokensDeducted": 100,
  "tokensRemaining": 9900
}

For incremental syncs, store the watermark after a full pull and use created_at_gte with sorting=uploaded on the next run.

Client info & balance

GET/getClientInfo

Cost: Free

Returns your account information and remaining request balance.

Parameters

Parameter	Type	Description
clientIdrequired	string	Your client ID — returned when your key was issued (trial keys: "trial-..." from verifyTrialKey).

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getClientInfo?clientId=YOUR_CLIENT_ID"

{
  "clientId": "YOUR_CLIENT_ID",
  "reportsLeft": 230,
  "reports": [],
  "createdDate": "2026-06-11T14:00:00.000Z"
}

Cities for country

GET/getCitiesForCountry

Cost: Free

Returns the list of cities available for the discovery city filter in a given country.

Parameters

Parameter	Type	Description
countryrequired	string	Country name, e.g. Germany, United States (case-sensitive).

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getCitiesForCountry?country=Germany"

["Berlin", "Munich", "Hamburg", "Cologne", "Frankfurt am Main", ...]

Creator categories

Values for the categories parameter in discovery (comma-separate multiple values):

fashion — Fashion & Style

fitness — Fitness & Wellness

beauty — Beauty & Cosmetics

sports — Athletics & Sports

food — Food & Drink

diet — Healthy Nutrition & Diet

veganism — Veganism & Vegetarianism

travel — Travel & Adventure

books — Books & Literature

interior — Home & Interior Design

comedy — Comedy

tech — Technology & Gadgets

art — Art & Creativity

lifestyle — Lifestyle

education — Education & Learning

family — Parenting & Family

media — Entertainment & Media

music — Music

lgbtq — LGBTQ+

gaming — Gaming

business — Business & Finance

automotive — Automotive & Vehicles

sustainability — Sustainability & Environment

animals — Animals & Pets

charity — Charity & Activism

politics — Politics

Platform coverage

Feature	Instagram	TikTok	YouTube	Twitch	Facebook	Snapchat
Creator profiles (getUserData)	✓	✓	✓	✓	✓	✓
Discovery search	✓	✓	✓	✓	✓	✓
Audience reports	✓	✓	✓	—	—	—
Content data (getContent)	✓	✓	✓	—	—	—
Data status & enrichment	✓	✓	✓	✓	—	—
City / gender / age filters	✓	✓	—	—	—	—
Business account mode	✓	—	—	—	—	—

Error handling

Errors are returned as JSON with an error field and a standard HTTP status code:

Response codes

400	Bad request — invalid or missing parameters.
401	Unauthorized — invalid, missing or expired API key.
403	Forbidden — insufficient request balance, or the feature is not enabled for your key.
404	Not found — the requested creator or content does not exist.
429	Rate limit or monthly volume exceeded — back off and retry later.
500	Server error — retry with exponential backoff.

Recommended retry strategy: exponential backoff starting at 1 s with a maximum of 3 retries; never retry 4xx responses except 429.

Ready to build?

Get a free trial key in minutes — 250 requests, all platforms, full production data.

Get your trial key

Social API Documentation

Overview

Authentication

Request budget & costs

Rate limits

Create trial key — step 1: request a verification code

Body parameters (JSON)

Response codes

Verify trial key — step 2: exchange the code for your key

Body parameters (JSON)

Response codes

Get creator profile

Parameters

Response codes

Check data status

Parameters

Bulk enrichment

Body parameters (JSON)

Discovery search

Parameters

Get content

Pagination parameters

Filter parameters

Client info & balance

Parameters

Cities for country

Parameters

Creator categories

Platform coverage

Error handling

Response codes

Ready to build?

About Us

Knowledge

Service

Legal