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.

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

Large content responses (getContent) 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.

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

Rate limits

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.

The tier limits above apply to keys booked via the self-serve Social API checkout. Organization keys generated in the influData app settings run at the default burst limit (25 req/s · 1,000 req/min) unless configured otherwise.

Media URLs

Every media field we return (profilePicURL, imageUrl, videoUrl, campaignLogo, watchlist thumbnails) points at private object storage. By default these are signed URLs that expire after 24 hours, which is why links kept in your own database later render as broken images. Signed URLs cannot be issued for longer than 7 days, that is a hard limit of the S3 signature standard.

Pick one of three ways to handle this:

• Stable media URLs. Add mediaUrls=stable to any request and every media field comes back as a permanent URL on /api/externalAPI/media/…. It never expires, needs no authentication, and works straight in an <img src>. Requesting it redirects (302) to a freshly signed storage URL, so your client only has to follow redirects, which browsers and common HTTP libraries do by default. These requests cost no requests from your budget. We can switch this on permanently for your organization, then every endpoint returns stable URLs and mediaUrls=signed restores the old behaviour per request.
• Re-sign on demand. Store the link without its query string and hand it back to /signInfluDataAWSLink?link=… when you need it. You get a fresh 24-hour URL, and it costs no requests.
• Mirror the files. Download the bytes once and serve them from your own storage. The most robust option regardless of URL lifetimes, because creator media also disappears when the creator deletes the post.

GET /api/externalAPI/getUserById?platform=instagram&userId=248312442&mediaUrls=stable

{
  "profilePicURL": "https://app.infludata.com/api/externalAPI/media/aHxpZy9wcm9maWxlcGljcy8…",
  ...
}

<!-- store it, embed it, it stays valid -->
<img src="https://app.infludata.com/api/externalAPI/media/aHxpZy9wcm9maWxlcGljcy8…" />

Never build URLs against our storage hosts yourself, and never strip the signature from a signed URL and request it directly. Both return 403.

Create trial key — step 1: request a verification code

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.

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
}

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

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.

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

Get creator profile

Cost: 1 request — 20 with includeAudienceReport=true

Returns a full creator profile: bio, follower/following counts, engagement metrics, verification status, creator demographics (country, city, language, gender), CPM estimates and the follower-growth history (dataLogTimePeriods with all/12-month/30-day series plus monthlyGrowthFollowers). With showDatalogAndScore=true the response additionally carries the quality scores (profileScore), the raw growth dataLog and the brand/creator collaboration timelines. With includeAudienceReport=true it includes audience demographics (age, gender, geo breakdown), interests and follower-quality metrics — audience age/gender splits live here, not on the core profile.

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 excerpt (organization key) — workspace assignments come inline:
{
  "_id": "507f1f77bcf86cd799439011",
  "username": "creatorhandle",
  "followers": 125000,
  ...profile fields...,

  "collections": [
    { "collectionId": "aB3xK9pQz1", "collectionName": "Q4 Fitness Prospects" }
  ],
  "collectionArray": ["aB3xK9pQz1"],
  "collectionCount": 1,
  "campaigns": [
    { "campaignId": "mK4nP8qR2s", "campaignName": "Winter Launch 2026", "isActive": true }
  ],
  "campaignArray": ["mK4nP8qR2s"],
  "campaignCount": 1,
  "commentThread": [ ...internal notes... ],
  "additionalFields": [ { "code": "xY9zW2vU4t", "value": "3500" } ],
  "stars": 4
}

Check data status

Cost: Free for the metadata — 1 request when a new data refresh is actually queued (duplicates within 48h are free)

Returns metadata about a creator: whether they exist in the database, data freshness, audience-report availability and timeline coverage. Also queues an instant data refresh (Instagram, TikTok, YouTube, LinkedIn — for Twitch the call is metadata-only), and optionally adds the creator to the weekly refresh schedule. Use it before getUserData to avoid spending requests on incomplete data.

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,
  "tokensDeducted": 0,
  "tokensRemaining": 230
}

Creators not in the database yet return isInDatabase: false with isBeingProcessed: true once the enrichment row is queued.

Bulk enrichment

Cost: 1 request per creator newly queued — duplicates within 48h are free

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

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

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 },
  "tokensDeducted": 2,
  "tokensRemaining": 228
}

Discovery search

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.

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=%22personal%20trainer%22,%22fitness%20coach%22&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": { "status": true, "error": "" }
}

Note: unlike most endpoints, discovery signals failures inside a 200 response — an exhausted budget or an empty result set returns { "status": false, "error": "…" }. Check the body, not just the HTTP status. Failed searches are not charged.

Get content

Cost: 1 request per content piece returned

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

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

• Passing offset/skipCount switches to the legacy offset mode, which returns a different shape — { content, count, limit, offset, … } instead of items/next_cursor — and answers empty result sets with 404. New integrations should use cursor pagination.
• imageUrl/videoUrl are null when media delivery is disabled for your key — the metrics and captions are unaffected.

Organization data

Beyond the public creator database, the API exposes your organization's own workspace — the same data your team works with in the influData app: collections (saved creator lists, including saved content pieces), campaigns (creator rosters, tracking setup, custom-field definitions), internal notes (per-creator comment threads) and custom fields (attributes your organization defines per creator). Use it to sync influData into your own CRM, data warehouse or reporting.

• Organization-scoped. Every endpoint reads and writes only the calling key's organization — other organizations' data is never accessible.
• Also available as MCP tools. The same campaigns, collections and metrics are exposed to Claude, ChatGPT and other LLM clients through the influData MCP server (read-only there, authenticated with the same API key).
• Signed URLs: profile pictures, note attachments and upload-type custom-field values come as short-lived signed URLs — fetch them immediately, or request permanent links instead (see Media URLs).

List collections

Cost: 1 request

Returns all creator collections of your organization. Collections with restricted access that the API principal cannot see are omitted.

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

{
  "collections": [
    {
      "collectionId": "aB3xK9pQz1",
      "collectionName": "Q4 Fitness Prospects",
      "name": "Q4 Fitness Prospects",
      "description": "Shortlist for the winter campaign",
      "elementCount": 34,
      "access": "organization",
      "color": "#22c55e",
      "created": "2026-05-02T09:14:00.000Z",
      "folderId": null,
      "pipelineColumns": null,
      "pipelineColumnOrder": null,
      "autoAddToPipeline": true,
      "accessTeams": [{ "orgId": "…", "orgName": "Your Team", "logoUrl": null }]
    }
  ],
  "count": 12
}

• collectionName and name carry the same value (both kept for backwards compatibility).
• pipelineColumns/pipelineColumnOrder describe the collection's kanban stages when pipeline mode is enabled; accessTeams lists the owning team plus teams the collection is shared with.
• The list also contains collections shared into your team by sibling teams (marked isSharedIn: true with sharedFromOrgId/sharedFromOrgName) and — when audience reports were unlocked — the virtual unlocked collection.

Get collection — creators with notes, fields & saved content

Cost: 1 request

Returns the creators saved in one collection as full profile objects — and hydrates each creator with your organization's internal data: commentThread (internal notes), additionalFields (custom-field values), stars (your team's rating) and collectionArray (which other collections the creator is saved in). Content pieces saved to the collection are returned in contentData.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getCollection?collectionId=aB3xK9pQz1"

{
  "userdata": [
    {
      "_id": "65abc123def456789abc1234",
      "_index": "instagram",
      "username": "creatorhandle",
      "displayName": "Creator Name",
      "followers": 125000,
      "country": "Germany",
      "engagementMean": "4.2 %",
      "profilePicURL": "https://... (signed, short-lived)",
      ...core profile fields...,

      "commentThread": [
        {
          "code": "k2j4h6g8s0",
          "user": "anna@yourcompany.com",
          "comment": "Met at OMR — open to a Q4 cooperation",
          "isPinned": false,
          "linkToResources": null,
          "timeStamp": "2026-07-02T10:15:00.000Z"
        }
      ],
      "additionalFields": [
        { "code": "xY9zW2vU4t", "value": "3500" },
        { "code": "pQ7rS5tU3v", "value": ["Confirmed"] }
      ],
      "stars": 4,
      "collectionArray": ["aB3xK9pQz1", "cD5eF7gH9i"],
      "collectionCount": 2
    }
  ],
  "contentData": [ ...content pieces saved to this collection... ],
  "metadata": {
    "additionalFields": [
      { "code": "xY9zW2vU4t", "label": "Budget (EUR)", "type": "number", "allowedValues": null },
      { "code": "pQ7rS5tU3v", "label": "Status", "type": "singleselect", "allowedValues": ["Contacted", "Confirmed", "Declined"] }
    ],
    "isOwner": true,
    "color": "#22c55e",
    "audienceReport": { ...aggregated audience of the collection... }
  },
  "count": 34
}

• metadata.additionalFields holds your organization's custom-field definitions — resolve each value's code against it (see Notes & custom fields).
• collectionArray is hydrated for collections up to 50 creators; larger collections skip it for speed. Collections with more than 50 creators additionally omit the heavy per-creator fields (profileScore, cpms, mentions and the latest-content arrays) — fetch those per creator via getUserData when needed.
• An unknown collectionId returns an empty 200 response (empty userdata), not a 404 — validate ids against getCollections.

Manage collections

Cost: 1 request each — renameCollection and deleteCollection are free

Create collections and manage their members from your own tooling. Changes appear in the influData app immediately.

POST https://app.infludata.com/api/externalAPI/createCollection       {"collectionName": "Q4 Prospects", "description": "…", "color": "#22c55e", "access": "organization"}
POST https://app.infludata.com/api/externalAPI/addToCollection        {"collectionId": "…", "objectIds": ["<creator _id>", "…"]}
POST https://app.infludata.com/api/externalAPI/removeFromCollection   {"collectionId": "…", "objectIds": ["<creator _id>"]}
POST https://app.infludata.com/api/externalAPI/renameCollection       {"collectionId": "…", "name": "New name", "description": "…"}
POST https://app.infludata.com/api/externalAPI/deleteCollection       {"collectionId": "…"}

• objectIds are influData creator _ids as returned by getUserData, discovery or getCollection. To save content pieces instead of creators, send contentIds (from getContent) in place of objectIds.
• New collections are visible organization-wide by default (access: "organization" — the optional access parameter accepts restricted for a private collection). The favorites collection cannot be deleted.

List campaigns

Cost: 1 request

Returns all campaigns of your organization with their creator rosters. For a single creator, the reverse lookup is even simpler: getUserData returns the creator's campaign memberships (with names) directly in campaigns.

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

{
  "campaigns": [
    {
      "campaignId": "mK4nP8qR2s",
      "campaignName": "Winter Launch 2026",
      "campaignDescription": null,
      "campaignLogo": "https://... (signed, short-lived)",
      "startingDate": "2026-10-01T00:00:00.000Z",
      "campaignPeriod": { "from": "2026-10-01T00:00:00.000Z", "to": null },
      "isActive": true,
      "creatorCount": 8,
      "creators": [
        {
          "creatorId": "65abc123def456789abc1234",
          "_id": "65abc123def456789abc1234",
          "username": "creatorhandle",
          "platform": "instagram",
          "overwriteName": null,
          "isActive": true,
          "isArchived": false,
          "isOnboarding": false
        }
      ]
    }
  ],
  "count": 3
}

• creatorId is the influData profile id — pass it to getUserData (_id is the same value, kept as an alias) or to addToCollection. Deleted roster entries are excluded.
• A campaign is isActive when it has started and is not archived; per creator, isActive means currently tracked (neither archived nor still onboarding).

Get campaign

Cost: 1 request

Returns one campaign in full detail: the creator roster with per-creator settings (pricing, individual custom-field values, contact preferences), campaign-level custom-field definitions, tracked terms and campaign goals.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getCampaign?campaignId=mK4nP8qR2s"

{
  "campaign": {
    "campaignId": "mK4nP8qR2s",
    "campaignName": "Winter Launch 2026",
    "campaignDescription": null,
    "campaignLogo": "https://... (signed, short-lived)",
    "startingDate": "2026-10-01T00:00:00.000Z",
    "setInactiveOn": null,
    "campaignPeriod": { "from": "2026-10-01T00:00:00.000Z", "to": null },
    "isActive": true,
    "folderId": null,
    "contentLabels": [],
    "campaignGoals": [ ... ],
    "customFields": [
      { "customFieldId": "aB3xK9pQz1", "customFieldName": "Fee (EUR)", "dataFormat": "number", "applyLevel": "creator", "trackingMethod": "manual" }
    ],
    "defaultCustomFields": [ ...built-in metric fields... ],
    "trackedMetrics": [
      { "metricId": "tR8kW3mN1p", "type": "hashtag", "value": "winterlaunch", "isExact": true, "isBrandTerm": false, "startingDate": "2026-10-01T00:00:00.000Z" }
    ],
    "creatorCount": 8,
    "creators": [
      {
        "creatorId": "65abc123def456789abc1234",
        "_id": "65abc123def456789abc1234",
        "username": "creatorhandle",
        "platform": "instagram",
        "overwriteName": null,
        "profilePicURL": "https://... (signed, short-lived)",
        "dateAdded": "2026-09-20T08:00:00.000Z",
        "isActive": true,
        "isArchived": false,
        "isOnboarding": false,
        "pricing": 3500,
        "enablePricing": true,
        "individualCustomFields": [ { "customFieldId": "aB3xK9pQz1", "value": "3500" } ],
        "customCreatorGoals": [],
        "shouldContactCreator": false,
        "creatorContactMethods": []
      }
    ]
  }
}

trackedMetricsholds the campaign's tracked terms — each entry has a type of hashtag, mention, text or url. App-internal state (dashboards, notification settings, roles) is not part of the API response.

Campaigns are read-only via the REST API — create and edit them in the influData app. Campaign performance metrics (reach, views, engagement per creator and per content piece) are currently exposed through the MCP server (get_campaign_metrics).

Internal notes & custom fields

Notes and custom fields are the org-internal data your team maintains on creators in the influData app. The API returns them on every creator inside getCollection responses and — for organization keys — on getUserData:

• Notes — commentThread: the per-creator comment thread. Each entry carries the author (user), text, pin state, timestamp and — when a file was attached — a short-lived signed URL in linkToResources.
• Custom-field definitions — metadata.additionalFields: the fields your organization defined in the app, each with code, label, type (string, number, boolean, date, singleselect, multiselect, upload) and allowedValues for the select types.
• Custom-field values — the per-creator additionalFields array: { "code": "…", "value": … } pairs — join on code with the definitions. Upload-type values resolve to signed, short-lived URLs.
• Rating & flags — stars (0–5 team rating), isBlack (on your blacklist).
• Membership — per creator, collections and campaignslist the creator's memberships including their names (collectionArray/campaignArray carry the plain ids) — returned by both getUserData and getCollection.

Notes, custom-field values and ratings are currently read-only via the API — your team edits them in the influData app. If your integration needs write access here, talk to us.

Content download links

Cost: 1 request (404s are not charged)

Resolves a fresh, direct CDN link for an Instagram or TikTok content piece — for downloading media into your own asset pipeline (transcription, archiving, reporting).

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.infludata.com/api/externalAPI/getContentDownloadLink?platform=instagram&code=CeLgPLAg14Q"

{
  "platform": "instagram",
  "code": "CeLgPLAg14Q",
  "links": [
    { "type": "video_1", "link": "https://... (CDN, valid ~6h)" },
    { "type": "image_1", "link": "https://..." }
  ]
}

Links are valid for roughly 6 hours — download immediately, never store the URL. Multi-image posts return one entry per slide (image_1, image_2, …).

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

• 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 on Instagram — TikTok history builds forward from the daily crawls — and an AI deep-dive pipeline).
• Signed media URLs: avatar and image/thumbnail URLs in responses are short-lived signed URLs (valid ~6–24 hours); videoUrl is the platform's own expiring CDN URL. Fetch the media immediately when importing, or request permanent links instead (see Media URLs).

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

Get watchlist

Cost: 1 request

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

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",
        "addedByMail": "teammate@yourcompany.com",
        "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

Cost: 10 requests

Starts continuous monitoring, enqueues a content backfill (12 months on Instagram; TikTok history builds forward from the daily crawls) 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).

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.

Remove creator from watchlist

Cost: 1 request

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 }

The call is idempotent: modified is false when the creator was not on the roster (still 200, still costs 1). Invalid platform/referenceId return 400.

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

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.

# 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, or use permanent links (see Media 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

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.

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

Creator details (deep dive)

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.

{
  "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 (default 56)
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=1..200 (default 50)
GET https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/top-comments         ?days=30 &limit=1..100 (default 20)
GET https://app.infludata.com/api/externalAPI/watchlist/creators/{platform}/{referenceId}/flagged-content      ?days=30 &limit=1..100 (default 50)

The windowed reads also accept absolute from & to ISO ranges instead of days. 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

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. The call costs 10 even when the dedupe reports an analysis is already active/exists — check the returned deepDive statuses before retrying. Creators not on the watchlist return 404 (not charged).

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.

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

Cost: Free

Returns your account information and remaining request balance.

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",
  "expiresAt": "2026-06-25T00:00:00.000Z"
}

expiresAtis present for trial keys only. A clientId that doesn't match the key returns 400.

Org usage & limits

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.

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

monthlyLimit, remaining and resetDate are null for keys on unmetered or lifetime-budget contracts.

Cities for country

Cost: Free

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

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

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

Unknown or misspelled countries return an empty array with 200, not an error.

Creator categories

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

Platform coverage

LinkedIn profiles can additionally be queued for enrichment via checkDataStatus and bulkAddToEnrich (profile retrieval for LinkedIn is not yet part of the public API). On-demand enrichment for Snapchat works when a username lookup misses; Twitch and Facebook profiles are served from the existing database only.

Error handling

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

Recommended retry strategy: exponential backoff starting at 1 s with a maximum of 3 retries; never retry 4xx responses except 429. Exception: discovery signals failures inside a 200 response via { "status": false } — check the body there.