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

# Creators API v2

> Search creators for free and fetch full profiles with v2 endpoints

<Note>
  * Search is free and uses the same filters as the existing Creators API.
  * Use the `userIds` returned by search to fetch full creator profiles.
</Note>

## Base URL

`https://api.topyappers.com`

## Authentication

All requests require an API key in the header:

```bash theme={null}
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

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](/creators-api/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)](/creators-api/parameters#sorting-creators-api).

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript JavaScript theme={null}
  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
  ```
</CodeGroup>

Example response:

```json theme={null}
{
  "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:

```json theme={null}
{
  "userIds": [
    "instagram_57971538386",
    "instagram_58848167468",
    "instagram_52172673568"
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  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"
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

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

```json theme={null}
{
  "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`).

<Tip>
  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.
</Tip>