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. When you later book a plan with the same email address, your trial key is automatically upgraded to a production key — no code changes needed.
Organization keys — for production use. Book a plan directly via the self-serve checkout on the Social API page — your production key arrives by email right after the purchase. Customers on influData app plans with API access can also generate keys in the 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 /watchlist/… (all watchlist reads)	1 request per call
POST /watchlist/creators	10 requests (starts monitoring, backfill & AI deep dive)
POST /watchlist/creators/…/deep-dive	10 requests
GET /checkDataStatus	Free
POST /bulkAddToEnrich	Free
GET /getUsage	Free
GET /getClientInfo	Free
GET /getCitiesForCountry	Free

Check your remaining balance anytime — organization keys use getUsage, trial keys use getClientInfo. Both are free.

Rate limits

Key type	Burst limit	Volume
Trial	2 req/s · 60 req/min	250 requests total, 14 days
Developer	5 req/s · 300 req/min	15,000 requests / month
Startup	10 req/s · 600 req/min	60,000 requests / month
Business	25 req/s · 1,000 req/min	250,000 requests / month

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.

Watchlist monitoring

The watchlist is a curated roster of Instagram and TikTok creators your organization monitors continuously: fresh follower and engagement stats, a live content feed (posts, reels, stories), comment monitoring with flag terms, AI sentiment and brand-safety deep dives, and alert events (early-viral detection, follower spikes, keyword hits).

Availability: requires an organization API key and the watchlist add-on enabled on your organization (contractual — contact influData). Without the add-on, all watchlist endpoints return 403.

One watchlist per organization. The API operates on the same watchlist as the influData app, and both share the same creator seat pool (sized by your plan). Seats are counted per person: verified sibling accounts of the same creator (e.g. their TikTok) are auto-linked into a person group and don't consume an extra seat.
Costs: all reads cost 1 request from your monthly budget. Adding a creator and manually re-running a deep dive cost 10 (they trigger recurring crawls, a 12-month content backfill and an AI deep-dive pipeline).
Signed media URLs: avatar and thumbnail URLs in responses are short-lived signed URLs (valid ~6–24 hours). Fetch the media immediately when importing — never store the URL itself.

Base path

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

Get watchlist

GET/watchlist

Cost: 1 request

Returns your organization's roster with labels, flag terms and seat usage.

Parameters

Parameter	Type	Description
withGrid	boolean	true to hydrate each creator with live signals (follower deltas, activity, engagement, latest pieces). Slower; still costs 1.
days / from & to	string	Stats window for withGrid (relative days or absolute ISO range). Default: 30 days.

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/watchlist"

{
  "watchlist": {
    "name": "Watchlist",
    "creators": [
      {
        "platform": "instagram",
        "referenceId": "65abc123def456789abc1234",
        "username": "creatorhandle",
        "displayName": "Creator Name",
        "profilePicURL": "https://... (signed, short-lived)",
        "followers": 125000,
        "country": "DE",
        "categories": ["media"],
        "labels": ["<labelId>"],
        "groupId": "66def...",
        "addedAt": "2026-07-01T09:00:00.000Z",
        "addedVia": "api"
      }
    ],
    "labels": [{ "id": "...", "name": "VIP", "color": "#1e88e5" }],
    "flagTerms": [{ "term": "scandal", "createdAt": "2026-07-01T09:00:00.000Z" }],
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-07-15T00:00:00.000Z"
  },
  "seatsUsed": 12,
  "maxSeats": 25
}

maxSeats is null if the plan lookup is temporarily unavailable (reads still succeed).

Add creator to watchlist

POST/watchlist/creators

Cost: 10 requests

Starts continuous monitoring, enqueues a 12-month content backfill and an AI deep dive (sentiment + brand safety, 24–48h SLA). Verified sibling platform accounts are added automatically under the same person seat (returned as linkedAdded).

Body parameters (JSON)

Parameter	Type	Description
platformrequired	string	instagram or tiktok.
usernamerequired	string	Exact handle, without @.

Example

curl -X POST "https://app.infludata.com/api/externalAPI/watchlist/creators" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram", "username": "creatorhandle"}'

{
  "success": true,
  "creator": { "platform": "instagram", "referenceId": "65abc...", "username": "creatorhandle", ... },
  "linkedAdded": [{ "platform": "tiktok", "referenceId": "66def...", "username": "creatorhandle", ... }],
  "deepDive": { "sentiment": "enqueued", "brandSafety": "enqueued" },
  "seatsUsed": 13,
  "maxSeats": 25
}

deepDive reports the pipeline state per analysis as a status string: enqueued, active, exists or error.

Response codes

200	Creator added (siblings in linkedAdded).
403	Watchlist full (seatsUsed = maxSeats) or the add-on/seats are not included in your plan.
404	Creator not found on this platform.
409	Creator already on the watchlist (existing entry returned in creator).
503	Seat verification temporarily unavailable — retry shortly (nothing charged).

Remove creator from watchlist

DELETE/watchlist/creators/{platform}/{referenceId}

Cost: 1 request

Parameters

Parameter	Type	Description
wholeGroup	boolean	true removes every platform account of the person group (frees the whole seat).

Example

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/watchlist/creators/instagram/65abc123def456789abc1234?wholeGroup=true"

{ "success": true, "removed": [{ "platform": "instagram", "referenceId": "65abc..." }], "modified": true }

Labels

Cost: 1 request each

Organize the roster with labels (max 20 per watchlist; colors are assigned automatically). Setting a creator's labels replaces the whole list; unknown label ids are silently dropped.

GET    https://app.infludata.com/api/externalAPI/watchlist/labels
POST   https://app.infludata.com/api/externalAPI/watchlist/labels                          {"name": "VIP"}
DELETE https://app.infludata.com/api/externalAPI/watchlist/labels/{labelId}
PUT    https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/labels   {"labels": ["<labelId>"]}

Content feed

GET/watchlist/content

Cost: 1 request

Reverse-chronological content stream across the whole roster — posts, reels and stories with captions, performance metrics and links to the original piece. This is the endpoint for syncing watchlist content into your CMS or tooling.

Parameters

Parameter	Type	Description
days / from & to	string	Window (relative days or absolute ISO range). Default: 30 days, max 365.
platform	string	instagram or tiktok. Default: both.
contentTypes	string	Comma-separated: post, reel, story (Instagram); video (TikTok).
limit	number	1–100 pieces per page. Default: 30.
before	string	ISO cursor — return only pieces older than this (paging back).
after	string	ISO cursor — return only pieces newer than this. Use for incremental syncs.

Example — incremental sync

# Full pull, then remember newestISO from the response
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/watchlist/content?days=7&limit=100"

# Next poll: only pieces newer than the last one you saw
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/watchlist/content?after=2026-07-27T15:28:11.000Z"

{
  "pieces": [
    {
      "contentId": "3949132417417327988",
      "contentType": "story",
      "imageUrl": "https://... (signed, valid ~6-24h)",
      "videoUrl": null,
      "platformLink": null,
      "postUrl": "https://www.instagram.com/stories/creatorhandle/3949132417417327988/",
      "uploaded": "2026-07-28T09:15:00.000Z",
      "caption": "…",
      "reach": 12500, "likes": 830, "comments": 41, "shares": 0, "saves": 0,
      "commentPositivityRate": 92,
      "language": "de",
      "locationString": null,
      "viralScore": 3.4, "viralMetric": "views",
      "creator": {
        "platform": "instagram",
        "referenceId": "65abc123def456789abc1234",
        "username": "creatorhandle",
        "displayName": "Creator Name"
      }
    }
  ],
  "hasMore": false,
  "newestISO": "2026-07-28T09:15:00.000Z",
  "timeframe": { "fromISO": "...", "toISO": "...", "days": 7 }
}

postUrl is the canonical link to the piece on its platform — use this field. platformLink (the crawled permalink) is kept for backwards compatibility but is nullfor Instagram stories; postUrl covers stories with a constructed story URL that resolves while the story is live (~24h — afterwards Instagram redirects to the creator's profile).
imageUrl / videoUrl are signed and short-lived — import the media right away, never store these URLs.
Pieces the early-viral detector currently flags carry viralScore and viralMetric.
commentPositivityRate is the share of positive comments on a 0–100 scale; null when comment analysis has not run for the piece.

Content piece by ID

GET/watchlist/content/{contentId}

Cost: 1 request (404s are free)

Fetch a single content piece by its influData contentId — the id returned by the content feed and on content-bearing alert events. Same piece shape as the feed, including postUrl and fresh signed media URLs. Typical use: an alert event names a piece and you pull its full data with one call.

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/watchlist/content/3949132417417327988"

{
  "contentId": "3949132417417327988",
  "contentType": "story",
  "postUrl": "https://www.instagram.com/stories/creatorhandle/3949132417417327988/",
  "uploaded": "2026-07-28T09:15:00.000Z",
  "reach": 12500, "likes": 830, "comments": 41,
  "creator": { "platform": "instagram", "referenceId": "65abc...", "username": "creatorhandle", "displayName": "Creator Name" }
}

Response codes

200	The piece.
400	Malformed contentId.
404	The piece does not exist or does not belong to a creator on your watchlist (not charged).

Creator details (deep dive)

GET/watchlist/creators/{platform}/{referenceId}/details

Cost: 1 request

The full per-creator payload: core profile fields, follower growth series with milestones, activity stats, the creator's content in the window, audience demographics, sentiment and brand-safety summaries, and the deep-dive pipeline status.

Parameters

Parameter	Type	Description
days / from & to	string	Content + chart window. Default: 90 days.
contentLimit	number	1–200 content pieces. Default: 30.

Response shape

{
  "creator": { ...profile fields... },
  "growth": { "points": [...], "deltas": {...}, "milestones": [...] },
  "activity": { "postsLast7d": 4, "postsLast30d": 19, "engagementWindow": 2.4, ... },
  "content": [{ "contentId": "...", "postUrl": "...", "platformLink": "...", ... }],
  "sentiment": { ... },
  "audience": { ... },
  "brandSafety": { ... },
  "reportStatus": { ... },
  "timeframe": { ... }
}

Audience demographics, sentiment and brand safety require the creator to be on your watchlist (the seat is the entitlement) and their deep-dive reports to have completed — reportStatus shows the pipeline progress.

Per-creator monitoring reads

Cost: 1 request each

GET https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/sentiment-timeline   ?granularity=week|month &sinceDays=42..365
GET https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/brand-mentions       ?days=90
GET https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/flagged-comments     ?days=30 &limit=50
GET https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/top-comments         ?days=30 &limit=20
GET https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/flagged-content      ?days=30 &limit=50

Flagged comments/content are matched against your organization's flag terms (managed in the influData app). Creators not on your watchlist return empty payloads, not errors.

Re-run deep dive

POST/watchlist/creators/{platform}/{referenceId}/deep-dive

Cost: 10 requests

Re-enqueues the sentiment + brand-safety analysis for a rostered creator (deduped server-side against already-running pipelines). Use after major events when you want fresh AI summaries before the next scheduled run.

Alert events

GET/watchlist/alert-events

Cost: 1 request

Recent alert events from your watchlist's alert rules: early-viral detection, viral posts, new content, keyword matches, mentions by other accounts, follower spikes and sentiment drops.

Parameters

Parameter	Type	Description
since	string	ISO 8601 timestamp — only events created after it. Poll incrementally: store the newest createdAt you have seen and pass it on the next call (recommended interval: 5–15 minutes).
platform	string	instagram or tiktok.
referenceId	string	Limit to one creator.
limit	number	1–100 events. Default: 30.

Example — incremental polling

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/watchlist/alert-events?since=2026-07-28T09:00:00Z"

{
  "events": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d0e1",
      "ruleId": "rule-1",
      "ruleType": "early_viral",
      "ruleName": "Early viral detector",
      "platform": "instagram",
      "referenceId": "65abc123def456789abc1234",
      "creatorUsername": "creatorhandle",
      "creatorDisplayName": "Creator Name",
      "title": "A reel by Creator Name is taking off",
      "description": "Views growing 4.2× faster than usual — …",
      "link": "https://app.infludata.com/watchlist/instagram/65abc...",
      "contentId": "3949132417417327988",
      "contentUrl": "https://www.instagram.com/stories/creatorhandle/3949132417417327988/",
      "payload": { ... },
      "createdAt": "2026-07-28T09:21:33.000Z"
    }
  ],
  "count": 1
}

Content-bearing events (viral_post, early_viral, new_content, keyword_match, mentioned_by_others) identify the triggering piece via contentId and contentUrl (direct link to the piece; for Instagram stories a constructed story URL that resolves while the story is live). Fetch the full piece via content piece by ID. Both fields are null for rule-level events (follower_change, sentiment_drop) and for keyword_match events triggered by comment hits — those carry payload.commentId (and payload.connectedContent when the parent piece is known) instead. True push webhooks (signed deliveries to your URL) are on the roadmap — polling since is the supported integration until then.

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"
}

Org usage & limits

GET/getUsage

Cost: Free

Returns your organization's monthly request budget: plan limit, requests used this month, remaining budget, the next reset date and your active keys (masked). Organization keys only — trial keys use getClientInfo.

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getUsage"

{
  "orgId": "YOUR_CLIENT_ID",
  "monthlyLimit": 15000,
  "currentMonthUsed": 4210,
  "remaining": 10790,
  "resetDate": "2026-08-01T00:00:00.000Z",
  "audienceReportsEnabled": true,
  "keys": [
    { "id": "aB3xYz9QwE", "name": "Production", "maskedKey": "••••••••••••••••••••••••••x7Kd", "createdAt": "2026-07-01T09: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)	✓	✓	✓	—	—	—
Watchlist monitoring	✓	✓	—	—	—	—
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. Ready for production? Book a plan self-serve and your key arrives right after checkout.

Get your trial key

See plans & self-serve checkout