# Effect

Schemas

Camera effects, filters and lenses creators use in their videos, with their creator and how many posts use them.

## Endpoints

1 endpoint returns effects on TikTok.

- [GETTikTok Effect API`/v1/tiktok/effect`](https://socialtap.dev/docs/reference/tiktok/effect/index.md)

## Schema

Every endpoint above returns this object as `data`. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (tiktok, …). |
| `id` | `string` | Platform-native effect ID (string; TikTok's effect ID, the number ending its /effect/ link). |
| `url` | `string` (uri) | Canonical public page of the effect. |
| `name` | `string` | The effect's name as the platform shows it. |
| `description` | `string` or `null` | The creator's description of the effect; null when empty or not exposed. |
| `creator` | `object` | The account that made the effect. Fields are null where the platform names no account (TikTok's own effects show only a display name). |
| `creator.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `creator.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `creator.display_name` | `string` or `null` | Display name shown on the profile. |
| `creator.url` | `string` (uri) or `null` | Canonical profile URL. |
| `creator.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `creator.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `is_official` | `boolean` or `null` | True when the platform itself made the effect, false for an effect made by a community creator; null when not exposed. |
| `icon_url` | `string` (uri) or `null` | The effect's icon image URL. Platform CDN URLs can expire within hours. |
| `media` | `object[]` | Preview images and videos the platform shows of the effect in use; \[\] if none or not exposed. |
| `media[].type` | `string` | Kind of file. New values may be added; treat unknown values as other.<br>One of `image`, `video`, `audio`, `gif` |
| `media[].url` | `string` (uri) or `null` | Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at. |
| `media[].expires_at` | `string` (date-time) or `null` | When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire. |
| `media[].thumbnail_url` | `string` (uri) or `null` | Poster or preview image URL. |
| `media[].width` | `integer` or `null` | Width in pixels. |
| `media[].height` | `integer` or `null` | Height in pixels. |
| `media[].duration_ms` | `integer` or `null` | Duration in milliseconds (video and audio only). |
| `media[].alt_text` | `string` or `null` | Accessibility text provided by the author or platform. |
| `published_at` | `string` (date-time) or `null` | When the effect was published, RFC 3339 UTC. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.post_count` | `integer` or `null` | Public posts made with the effect, as the platform counts them (TikTok's "videos" figure on the effect page). |
| `metrics.total_view_count` | `integer` or `null` | Views across all posts made with the effect. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.tiktok` | `object` or `null` | A TikTok effect's own fields. |
| `platform_specific.tiktok.creator_sec_uid` | `string` or `null` | The creator's secUid, TikTok's account key that survives a rename; null for TikTok's own effects. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.post_count from "304.5M videos"). A list path (media) means the list may be incomplete. \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, effect endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/effect/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)