GET /v1/creators

Returns a paginated list of the creators in your organization. A creator is a named entity that groups one or more accounts — the same person on TikTok and on Instagram is one creator with two accounts.

Each creator is returned with its hydrated accounts[] and an overall_stats aggregate across those accounts. For the flat account list without the creator grouping, use GET /v1/bloggers.

📋 Overview

🔐 Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

📝 Query Parameters

There is no sort parameter: creators are always ordered by created_at descending, newest first. To order by reach, fetch the accounts and sort client-side.

Example Request

# All creators, first 25
curl -X GET "https://api.influtics.com/v1/creators?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search by name — percent-encode the Cyrillic value
curl -X GET "https://api.influtics.com/v1/creators?name=%D0%9C%D0%B0%D1%80%D0%B8%D1%8F" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Second page
curl -X GET "https://api.influtics.com/v1/creators?limit=25&offset=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

📤 Response

{
  "success": true,
  "data": {
    "creators": [
      {
        "id": "1f0c9a5e-6b2d-4a17-9c3e-7d8b2f4a1c90",
        "display_name": "Kate Comfortt",
        "created_at": "2026-02-14T10:02:00Z",
        "updated_at": "2026-10-19T22:03:12Z",
        "overall_stats": {
          "video_count": 57,
          "number_of_subscribers": 243700,
          "total_views": 25180000,
          "average_views": 441930,
          "median_views": 312000
        },
        "accounts": [
          {
            "id": "1b7c4e90-3a55-4d21-9f08-6c2ad5b19e34",
            "channel_name": "Kate Comfortt",
            "channel_username": "katecomfortt",
            "channel_thumbnail": "https://xhrjtpcqcdqwcdiqrhfw.supabase.co/storage/v1/object/public/avatars/katecomfortt.jpg",
            "url": "https://www.instagram.com/katecomfortt",
            "platform": "instagram",
            "is_tracked": true,
            "tracking_id": "8c3f2b71-0d64-4a92-b1f7-2e5c9a4d6b13",
            "tracked_at": "2026-02-14T09:31:00Z",
            "last_scraped_at": "2026-10-19T22:00:00Z",
            "campaign": "Авито Недвиж",
            "budget_per_video": 12000,
            "daily_videos_count": 3,
            "video_count": 42,
            "number_of_subscribers": 128400,
            "total_views": 18732000,
            "median_views": 312000,
            "avg_views": 446000,
            "created_at": "2026-01-08T11:02:41Z",
            "updated_at": "2026-10-19T22:03:12Z"
          },
          {
            "id": "3d90b2c8-77a1-4e5f-8c26-0b4e9a7d1f55",
            "channel_name": null,
            "channel_username": null,
            "channel_thumbnail": null,
            "url": null,
            "platform": null,
            "is_tracked": false,
            "tracking_id": null,
            "tracked_at": null,
            "last_scraped_at": null,
            "campaign": null,
            "budget_per_video": null,
            "daily_videos_count": 0,
            "video_count": 0,
            "number_of_subscribers": 0,
            "total_views": 0,
            "median_views": 0,
            "avg_views": 0,
            "created_at": null,
            "updated_at": null
          }
        ]
      }
    ],
    "pagination": {
      "total": 12,
      "limit": 25,
      "offset": 0,
      "has_more": false
    }
  },
  "meta": {
    "request_id": "3b7e1c04-9a2f-4d68-b1c5-0e8f2a6d9b34"
  }
}

creator fields

overall_stats fields

overall_stats reproduces the figures shown on the creators dashboard, including four deliberate behaviours worth knowing before you build totals on top of it:

1. Subscribers are summed, not maximised. A creator present on two platforms double-counts reach.
2. average_views is a video-count-weighted mean of per-account averages, reconstructed from video_count copies of each account's average. It is not the mean of the underlying per-video views.
3. An account with avg_views === 0 contributes nothing to average_views or median_views — it drops out of both denominators entirely. A creator whose accounts are all at zero therefore reports 0 rather than an average over them.
4. median_views is the upper median. For an even number of values it biases toward the higher one.

pagination fields

Pagination lives inside data, not in meta.

An empty page is not an empty result set: total is computed over the whole filtered set independently of offset, so paging past the end still reports the real total and has_more: false.

⚠️ Error Responses

All errors share the standard envelope { success: false, error: { code, message, request_id, ... } }. The table below lists every documented code and the conditions that trigger it.

A 403 means the key was recognised and can no longer be used — a revoked or deactivated credential — which is a different client-side fix from a 401, where the Authorization: Bearer header never arrived or was malformed. The two are deliberately distinct: a credential that never arrived versus one that arrived and is unusable.

This endpoint has no 400 response. Unlike GET /v1/bloggers, it takes no enumerated filter, and the only two numeric parameters are normalized rather than rejected. limit=abc, limit=5000, limit=0 and offset=-5 all return 200 with the value clamped.

📌 Notes

name must be percent-encoded, and it is a single value

name is matched as a case-insensitive substring of display_name. Two things bite callers:

1. It is one value, not an array. There is no multi-value form — ?name=a&name=b does not return the union of a and b, and no comma-splitting happens either (name=a,b searches for the literal text a,b). Pass one substring.

2. Percent-encode non-ASCII values. Cyrillic must be sent as its UTF-8 percent-encoding or the search silently matches nothing and returns an empty list:

Sending the raw value may work with some clients and silently fail with others, because whether the raw bytes survive depends on how the client builds the URL. Encode it and the behaviour is deterministic. Spaces become %20 (or +), and name itself must be part of the query string, not the path.

The %, _ and \ characters are treated as literal characters in the search rather than as SQL wildcards, so a name containing them — 100%_real — matches exactly that text.

Case folding for non-ASCII letters depends on the database collation. ASCII searches are reliably case-insensitive; for Cyrillic, verify against your own data before relying on a mixed-case query.

overall_stats.average_views vs accounts[].avg_views

The same metric has two different names in the same response, on purpose: the account object publishes avg_views (to match the other public account endpoints), while the creator aggregate publishes average_views (to match the dashboard). They are not two different numbers — pick the one your code path expects, and do not expect to find average_views on an account or avg_views on a creator.

accounts[] never drops a linked account

An account linked to a creator but with no statistics row of its own is still returned, zeroed, with its own UUID in id — so platform, channel_name, is_tracked, campaign and every statistic read null or 0. Such accounts exist in real organizations (a handful at present), so a platform: null entry inside accounts[] is a real account, not a malformed row.

accounts[] comes from the creator↔account link, not from the statistics view, which is why it survives that case.

is_tracked inside accounts[] means actively tracking

Same rule as the account list: is_tracked is true only while tracking is running, so a paused account reads false, exactly like an account you never tracked. A creator can therefore hold a mix of actively tracked, paused and never-tracked accounts. See the full explanation.

avg_likes, avg_comments and avg_reposts are not returned

Neither on the creator nor on any account inside accounts[]. The statistics view behind them aggregates views only, so there is no engagement average to compute — the fields are omitted rather than emitted as 0. For computed engagement averages use GET /v1/bloggers/by-username/{username}, where 0 means "no video data to average".

Ordering and clamping are fixed

Creators are always sorted by created_at descending. Numeric parameters are normalized silently:

• The response is scoped to the calling organization. A creator belonging to another organization is not visible and returns 404 NOT_FOUND from the by-id endpoint.
• These endpoints only read tables the organization already pays for and call no platform API, so they cost 0 credits.
• Statistics are as of the last platform refresh (accounts[].last_scraped_at), not the moment of this request.

Related: Creator by ID → | List Accounts → | Accounts for a Creator →