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

# Overview

> Discover viral TikTok content with powerful filtering options

# Viral Content API

The Viral Content API allows you to discover and analyze viral TikTok content. Filter by categories, countries, views, virality and follower ranges, dates, music and hook text, **AI-derived tags** (format, tone, look, setting, audience, production, CTA, emotion), **substring** fields on analyzed text, and **boolean content flags** (face visible, product, branded, and more).

## Key Features

<CardGroup cols={2}>
  <Card title="Category Filtering" icon="tags">
    Filter viral posts by content categories like comedy, dance, food, and more.
  </Card>

  <Card title="Geographic Targeting" icon="globe">
    Find viral content from specific countries and regions.
  </Card>

  <Card title="Virality Scoring" icon="fire">
    Filter by our proprietary virality score to find the most engaging content.
  </Card>

  <Card title="Music Discovery" icon="music">
    Search for viral posts using specific trending sounds and music.
  </Card>
</CardGroup>

## Authentication

All requests require an API key passed in the `x-ty-api-key` header.

```bash theme={null}
curl -X POST https://api.topyappers.com/api/v1/viral-content \
  -H "x-ty-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": ["Music"],
    "viewsMin": 100000,
    "page": 1,
    "pageSize": 12
  }'
```

## Request parameters

All parameters are sent in the **JSON request body** (optional unless noted). Omit a field, use an empty array `[]`, or `null` where documented to apply no filter for that field.

### Core filters

| Parameter          | Type      | Description                                                                                                    |
| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------- |
| `categories`       | string\[] | Content categories. Values must match the **category enum** in OpenAPI (e.g. Arts, Fashion, Gaming, Music, …). |
| `countries`        | string\[] | Full **country names** as in OpenAPI (e.g. `United States`, `United Kingdom`).                                 |
| `viewsMin`         | integer   | Minimum view count (omit or `0` for no lower bound).                                                           |
| `viewsMax`         | integer   | Maximum view count (omit or `0` for no upper bound).                                                           |
| `viralityScoreMin` | float     | Minimum virality score.                                                                                        |
| `viralityScoreMax` | float     | Maximum virality score.                                                                                        |
| `followersMin`     | integer   | Minimum creator follower count.                                                                                |
| `followersMax`     | integer   | Maximum creator follower count.                                                                                |
| `dateCreatedFrom`  | string    | Post created on or after this date (`YYYY-MM-DD`).                                                             |
| `dateCreatedTo`    | string    | Post created on or before this date (`YYYY-MM-DD`).                                                            |
| `musicTitle`       | string    | Case-insensitive **partial** match on music/sound title.                                                       |
| `hook`             | string    | Case-insensitive **partial** match on analyzed hook text.                                                      |

### AI analysis — tag arrays (OR within each field)

For each array below, a post matches if its stored tag equals **any** value you send. Values are **fixed snake\_case strings**; see the linked schema in `openapi.json` for the complete enum per field.

| Parameter             | Type      | OpenAPI schema (enum) | Maps to analyzed field      |
| --------------------- | --------- | --------------------- | --------------------------- |
| `contentFormats`      | string\[] | `ContentFormat`       | `content_format`            |
| `contentTones`        | string\[] | `ContentTone`         | `content_tone`              |
| `visualStyles`        | string\[] | `VisualStyle`         | `visual_style`              |
| `videoSettings`       | string\[] | `VideoSetting`        | `setting` (filming setting) |
| `targetDemographics`  | string\[] | `TargetDemographic`   | `target_demographic`        |
| `productionQualities` | string\[] | `ProductionQuality`   | `production_quality`        |
| `ctaTypes`            | string\[] | `CtaType`             | `cta_type`                  |
| `primaryEmotions`     | string\[] | `PrimaryEmotion`      | `primary_emotion`           |

### AI analysis — text contains

Case-insensitive substring match. Special regex characters in your string are treated **literally** (escaped server-side).

| Parameter                 | Type   | Description                                            |
| ------------------------- | ------ | ------------------------------------------------------ |
| `videoTopicContains`      | string | Substring match on `video_topic`.                      |
| `contentCategoryContains` | string | Substring match on content niche / `content_category`. |
| `productCategoryContains` | string | Substring match on `product_category`.                 |
| `brandMentionedContains`  | string | Substring match on `brand_mentioned`.                  |
| `colorPaletteContains`    | string | Substring match on `color_palette`.                    |

### Content flags (booleans)

Omit the field for **no filter**. `true` / `false` restrict to posts that pass the corresponding analyzed signal.

| Parameter          | Type    | Description                |
| ------------------ | ------- | -------------------------- |
| `hasFace`          | boolean | Visible face in the video. |
| `hasProduct`       | boolean | Product visible.           |
| `isBranded`        | boolean | Branded / sponsored-style. |
| `isPromotional`    | boolean | Promotional.               |
| `hasTextOverlay`   | boolean | On-screen text overlay.    |
| `isTrendingFormat` | boolean | Tagged as trending format. |
| `isAiGenerated`    | boolean | AI-generated look.         |

### Pagination

| Parameter  | Type    | Description                                       |
| ---------- | ------- | ------------------------------------------------- |
| `page`     | integer | Page number (default: `1`, minimum: `1`).         |
| `pageSize` | integer | Results per page (default: `12`, maximum: `100`). |

## Sorting

The Viral Content API does **not** take `sortBy` / `sortOrder` in the request body. Results are **always returned in a fixed order**:

* **Primary:** post **creation time** (`date_created` on the post), **newest first** (descending).

So the first items on page 1 are the **most recently created** viral posts that match your filters. Use `dateCreatedFrom` / `dateCreatedTo` to narrow the time window; ordering within that window remains **newest first**.

## Pricing

Each request costs **1 credit per returned content**. For example, if you request `pageSize: 12` and receive 12 results, that costs 12 credits.

## Rate Limits

The Viral Content API is subject to rate limits. If you exceed the limit, you'll receive a `429` response with a `retryAfter` field indicating how long to wait before retrying.