# Trends Search

Search for trending videos on TikTok and YouTube by keyword. Results include video metadata, stats, and author info.

## Search Videos

```
GET /v1/trends/search
```

### Request Parameters

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `keyword` | string | Yes | — | Search keyword |
| `platform` | string | Yes | — | One of: `tiktok`, `youtube` |
| `cursor` | string | No | — | Pagination cursor from previous response |
| `region` | string | No | — | Two-letter ISO 3166-1 country code (e.g. `US`, `DE`, `JP`). Omit for all regions. |
| `days` | number | No | — | Filter to videos published within the last N days. Common values: `0` (all time), `1` (24h), `7` (week), `30` (month), `90` (3 months), `180` (6 months). Omit for all time. |

### Example

```bash
curl -X GET "https://api.influtics.com/v1/trends/search?keyword=marketing&platform=tiktok" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "videos": [
      {
        "id": "...",
        "url": "...",
        "cover": "...",
        "stats": {
          "plays": 1000,
          "likes": 100,
          "comments": 10,
          "shares": 5
        },
        "author": {
          "username": "...",
          "cover": "..."
        }
      }
    ],
    "cursor": "next_page_token",
    "hasMore": true
  },
  "meta": {
    "request_id": "uuid",
    "processing_time_ms": 450,
    "credits_used": 1
  }
}
```

### Credits

1 credit per successful search request. No credit charged for validation errors or upstream failures.

### Rate Limits

Monthly limits per plan:

| Plan | Requests/Month |
|------|---------------|
| Free | Not available |
| Pro | 1,000 |
| Business | 6,000 |

When the limit is exceeded, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating when the limit resets (start of next month).

### Error Responses

| Status | Code | When |
|--------|------|------|
| 400 | `VALIDATION_ERROR` | Missing `keyword` or invalid `platform` |
| 401 | `AUTHENTICATION_FAILED` | Missing or invalid API key |
| 429 | `RATE_LIMIT_EXCEEDED` | Monthly trends limit exceeded |
| 502 | `EXTERNAL_API_ERROR` | Upstream search service failed |
| 500 | `INTERNAL_ERROR` | Unexpected error |