Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.topyappers.com/llms.txt

Use this file to discover all available pages before exploring further.

  • 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

EndpointCost
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

  1. Search creators with filters (free) → returns userIds
  2. Get creators by passing those userIds → returns full creator objects
  3. 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"
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"
    ]
  }'

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