Creators API v2

Search is free and uses the same filters as the existing Creators API.
Use the userIds returned by search to fetch full creator profiles.

Base URL

https://api.topyappers.com

Authentication

All requests require an API key in the header:

x-ty-api-key: your-api-key

Pricing

Endpoint	Cost
Search creators (`GET /api/v2/creators/search`)	Free
Get creators by ID (`POST /api/v2/creators/get`)	1 credit per influencer

Rate limits

60 requests per minute per API key (returns 429 with Retry-After when exceeded).

Workflow

Search creators with filters (free) → returns userIds
Get creators by passing those userIds → returns full creator objects
Paginate with page and perPage

1) Search creators (free)

GET /api/v2/creators/search

Headers:

x-ty-api-key: your-api-key

Query parameters:

Same filters as v1 creators: performance (followers, average views/likes, engagement rate), posting cadence (uploadsPerWeek*, uploadsPerMonth*), average video duration, promotion / affiliate / sponsorship post counts, account type, language, hashtags, demographics, content & geography, email, sorting, and pagination. See Available parameters.
Defaults: page=1, perPage=10.

Sorting

Use sortBy and sortOrder on the query string the same way as v1 creators. Default: sortBy=date_created, sortOrder=desc (newest / most recently updated in our index first)—important when you care about date added or recency rather than only follower size. Full detail, allowed sortBy values, and examples: Sorting (Creators API).

curl -X GET "https://api.topyappers.com/api/v2/creators/search?source=instagram&country=France&page=1&perPage=10" \
  -H "x-ty-api-key: $TY_API_KEY"

const params = new URLSearchParams({
  source: 'instagram',
  country: 'France',
  page: '1',
  perPage: '10',
});

const res = await fetch(
  `https://api.topyappers.com/api/v2/creators/search?${params.toString()}`,
  {
    headers: {
      'x-ty-api-key': process.env.TY_API_KEY,
    },
  },
);

const data = await res.json();
// data.response.data => array of userIds to use in the next step

Example response:

{
  "message": "OK",
  "params": {
    "page": 1,
    "perPage": 10
  },
  "response": {
    "data": [
      "instagram_57971538386",
      "instagram_58848167468",
      "instagram_52172673568",
      "instagram_74310952606",
      "instagram_47313147334",
      "instagram_1101500353",
      "instagram_67481263644",
      "instagram_67147724287",
      "instagram_54567535596",
      "instagram_9053965104"
    ],
    "page": 1,
    "next_page": 0,
    "total_pages": 10000
  }
}

2) Get creators by ID

POST /api/v2/creators/get

Headers:

x-ty-api-key: your-api-key
Content-Type: application/json

Body:

{
  "userIds": [
    "instagram_57971538386",
    "instagram_58848167468",
    "instagram_52172673568"
  ]
}

curl -X POST "https://api.topyappers.com/api/v2/creators/get" \
  -H "Content-Type: application/json" \
  -H "x-ty-api-key: $TY_API_KEY" \
  -d '{
    "userIds": [
      "instagram_57971538386",
      "instagram_58848167468",
      "instagram_52172673568"
    ]
  }'

const body = {
  userIds: [
    'instagram_57971538386',
    'instagram_58848167468',
    'instagram_52172673568',
  ],
};

const res = await fetch('https://api.topyappers.com/api/v2/creators/get', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-ty-api-key': process.env.TY_API_KEY,
  },
  body: JSON.stringify(body),
});

const payload = await res.json();
// Creator rows: payload.response.data (each object is snake_case)

Response shape (public API)

POST /api/v2/creators/get returns an envelope: message, requestedIds (echo of the ids you sent), and response (paginated payload from the backend). Creator profiles live in response.data — snake_case, same projection as v1. Optional fields may be null; date_created_timestamp appears when the index provides it. You can also send user_ids instead of userIds in the request body.

{
  "message": "OK",
  "requestedIds": ["UCECuDLnD9j3y901oNxJFerw"],
  "response": {
    "data": [
      {
        "user_id": "UCECuDLnD9j3y901oNxJFerw",
        "handle": "April Apple Tech",
        "nickname": "April Apple Tech",
        "bio": "ℹ Tech Review \nℹ Business\nExplore my experience In usage of Gadgets\n…",
        "source": "youtube",
        "email": null,
        "categories": [
          "Tech Reviews",
          "Gadget Reviews",
          "Smartphone Comparisons",
          "Business Technology"
        ],
        "followers": 2500,
        "following": 0,
        "total_videos": 296,
        "total_likes": 0,
        "avg_views": 35,
        "avg_likes": 3,
        "avg_comments": 1,
        "engagement_rate": 0.11,
        "main_website": null,
        "websites": [],
        "description": null,
        "promoted_products": ["DIHRAMS", "iphone"],
        "best_promotion_niches": [
          "Consumer Electronics",
          "Mobile Devices",
          "Tech Accessories",
          "Online Retailers",
          "Business Software"
        ],
        "main_category": "Technology",
        "country": "United Arab Emirates",
        "date_created_timestamp": 1775636932.147,
        "avatar_url": "https://images.0xw.app/avatars/creators/bd6493d02eaf43ad9740efa20ec08cd1.png",
        "age": "10-19",
        "gender": "male",
        "account_type": "ugc",
        "race": "black",
        "hair_color": "white",
        "body_complexion": "hulk",
        "language": "english",
        "hashtags": ["iphone17", "cinimaticvideo", "iphoneair", "shotoniphone"],
        "uploads_per_week": 0.39,
        "uploads_per_month": 1.66,
        "avg_video_duration_seconds": null,
        "promotions_count": 2,
        "affiliate_posts_count": 0,
        "sponsorship_posts_count": 0
      }
    ],
    "page": 1,
    "next_page": 0,
    "total_pages": 1
  }
}

GET /api/v1/creators uses the same creator objects inside response.data, with params instead of requestedIds. Field reference: openapi.json → components.schemas.Creator (includes a full example).

Use next_page from the search response to continue fetching IDs, then call POST /api/v2/creators/get with those IDs to page through profiles.

Creator Endpoints

Base URL

Authentication

Pricing

Rate limits

Workflow

1) Search creators (free)

Sorting

2) Get creators by ID

Response shape (public API)

Available Parameters

​Base URL

​Authentication

​Pricing

​Rate limits

​Workflow

​1) Search creators (free)

​Sorting

​2) Get creators by ID

​Response shape (public API)

Available Parameters

Base URL

Authentication

Pricing

Rate limits

Workflow

1) Search creators (free)

Sorting

2) Get creators by ID

Response shape (public API)