# Migrating from another provider

> Paths follow the `/v1/<platform>/…` pattern and take your key in the `x-api-key` header, so most clients only change the base URL and the key.

- **Web page:** https://lurkapi.com/docs/switching

## The switch

1. [Get a LurkAPI key](https://lurkapi.com/login?next=/dashboard). Keys start with `lk_live_`.
2. Change the base URL to `https://api.lurkapi.com`. Paths stay the same.
3. Keep sending the key in `x-api-key`, and check your error handling against the differences below.

Paths and the `x-api-key` header match ScrapeCreators-style APIs, so a client written for one usually works after changing the base URL:

curl:

```bash
curl "https://api.lurkapi.com/v1/facebook/adLibrary/search/ads?query=running+shoes&country=US&status=active" \
  -H "x-api-key: YOUR_API_KEY"
```

## Endpoints

Endpoints cost 1–5 credits per call.

| Path | Endpoint | Cost |
| --- | --- | --- |
| `/v1/facebook/adLibrary/search/ads` | [Facebook: Search Ad Library ads](https://lurkapi.com/docs/facebook/search-ads.md) | 1 credit |
| `/v1/facebook/adLibrary/company/ads` | [Facebook: Ad Library ads by company](https://lurkapi.com/docs/facebook/company-ads.md) | 1 credit |
| `/v1/facebook/adLibrary/ad` | [Facebook: Ad Library ad details](https://lurkapi.com/docs/facebook/ad.md) | 1 credit |
| `/v1/facebook/adLibrary/search/companies` | [Facebook: Search Ad Library companies](https://lurkapi.com/docs/facebook/search-companies.md) | 1 credit |
| `/v1/facebook/profile` | [Facebook: Public profile](https://lurkapi.com/docs/facebook/profile.md) | 1 credit |
| `/v1/facebook/post` | [Facebook: Public post](https://lurkapi.com/docs/facebook/post.md) | 1 credit |
| `/v1/reddit/subreddit` | [Reddit: Subreddit posts](https://lurkapi.com/docs/reddit/subreddit-posts.md) | 1 credit |
| `/v1/reddit/subreddit/details` | [Reddit: Subreddit details](https://lurkapi.com/docs/reddit/subreddit-details.md) | 1 credit |
| `/v1/reddit/subreddit/search` | [Reddit: Subreddit search](https://lurkapi.com/docs/reddit/subreddit-search.md) | 1 credit |
| `/v1/reddit/search` | [Reddit: Search Reddit](https://lurkapi.com/docs/reddit/search.md) | 1 credit |
| `/v1/reddit/post/comments` | [Reddit: Post comments](https://lurkapi.com/docs/reddit/post-comments.md) | 1 credit |
| `/v1/youtube/video` | [YouTube: Video details](https://lurkapi.com/docs/youtube/video.md) | 1 credit |
| `/v1/youtube/video/transcript` | [YouTube: Video transcript](https://lurkapi.com/docs/youtube/transcript.md) | 1 credit |
| `/v1/youtube/video/comments` | [YouTube: Video comments](https://lurkapi.com/docs/youtube/comments.md) | 1 credit |
| `/v1/youtube/video/comment/replies` | [YouTube: Comment replies](https://lurkapi.com/docs/youtube/comment-replies.md) | 1 credit |
| `/v1/youtube/channel` | [YouTube: Channel details](https://lurkapi.com/docs/youtube/channel.md) | 1 credit |
| `/v1/youtube/channel-videos` | [YouTube: Channel videos](https://lurkapi.com/docs/youtube/channel-videos.md) | 1 credit |
| `/v1/youtube/channel/shorts` | [YouTube: Channel Shorts](https://lurkapi.com/docs/youtube/channel-shorts.md) | 1 credit |
| `/v1/youtube/search` | [YouTube: Search YouTube](https://lurkapi.com/docs/youtube/search.md) | 1 credit |
| `/v1/tiktok/profile` | [TikTok: Profile](https://lurkapi.com/docs/tiktok/profile.md) | 1 credit |
| `/v2/tiktok/video` | [TikTok: Video details](https://lurkapi.com/docs/tiktok/video.md) | 1 credit |
| `/v1/tiktok/video/transcript` | [TikTok: Video transcript](https://lurkapi.com/docs/tiktok/transcript.md) | 1 credit; 5 if speech-to-text runs |
| `/v3/tiktok/profile/videos` | [TikTok: Profile videos](https://lurkapi.com/docs/tiktok/profile-videos.md) | 1 credit |
| `/v1/tiktok/video/comments` | [TikTok: Video comments](https://lurkapi.com/docs/tiktok/comments.md) | 1 credit |
| `/v1/tiktok/video/comment/replies` | [TikTok: Comment replies](https://lurkapi.com/docs/tiktok/comment-replies.md) | 1 credit |
| `/v1/tiktok/search/hashtag` | [TikTok: Hashtag videos](https://lurkapi.com/docs/tiktok/hashtag-videos.md) | 1 credit |
| `/v1/tiktok/song` | [TikTok: Song](https://lurkapi.com/docs/tiktok/song.md) | 1 credit |
| `/v1/tiktok/song/videos` | [TikTok: Song videos](https://lurkapi.com/docs/tiktok/song-videos.md) | 1 credit |
| `/v1/tiktok/ad-library/search` | [TikTok: Search TikTok Ad Library](https://lurkapi.com/docs/tiktok/ad-library-search.md) | 1 credit |
| `/v1/tiktok/ad-library/ad` | [TikTok: TikTok Ad Library ad](https://lurkapi.com/docs/tiktok/ad-library-ad.md) | 1 credit |
| `/v1/tiktok/user/live` | [TikTok: Live status](https://lurkapi.com/docs/tiktok/live.md) | 1 credit |
| `/v1/tiktok/user/stories` | [TikTok: Public stories](https://lurkapi.com/docs/tiktok/stories.md) | 1 credit |
| `/v1/tiktok/product` | [TikTok: TikTok Shop product](https://lurkapi.com/docs/tiktok/product.md) | 1 credit |
| `/v1/google/adLibrary/advertisers/search` | [Google: Search Google advertisers](https://lurkapi.com/docs/google/search-advertisers.md) | 1 credit |
| `/v1/google/company/ads` | [Google: Google ads by company](https://lurkapi.com/docs/google/company-ads.md) | 1 credit |
| `/v1/google/ad` | [Google: Google ad details](https://lurkapi.com/docs/google/ad.md) | 1 credit |
| `/v1/bluesky/profile` | [Bluesky: Profile](https://lurkapi.com/docs/bluesky/profile.md) | 1 credit |
| `/v1/bluesky/user/posts` | [Bluesky: User posts](https://lurkapi.com/docs/bluesky/user-posts.md) | 1 credit |
| `/v1/bluesky/post` | [Bluesky: Post](https://lurkapi.com/docs/bluesky/post.md) | 1 credit |
| `/v1/snapchat/profile` | [Snapchat: Profile and stories](https://lurkapi.com/docs/snapchat/profile.md) | 1 credit |
| `/v1/truthsocial/profile` | [Truth Social: Profile](https://lurkapi.com/docs/truthsocial/profile.md) | 1 credit |
| `/v1/truthsocial/user/posts` | [Truth Social: User posts](https://lurkapi.com/docs/truthsocial/user-posts.md) | 1 credit |
| `/v1/truthsocial/post` | [Truth Social: Post](https://lurkapi.com/docs/truthsocial/post.md) | 1 credit |
| `/v1/telegram/channel` | [Telegram: Channel](https://lurkapi.com/docs/telegram/channel.md) | 1 credit |
| `/v1/telegram/channel/posts` | [Telegram: Channel posts](https://lurkapi.com/docs/telegram/channel-posts.md) | 1 credit |
| `/v1/telegram/post` | [Telegram: Post](https://lurkapi.com/docs/telegram/post.md) | 1 credit |
| `/v1/twitter/tweet` | [X (Twitter): Tweet](https://lurkapi.com/docs/twitter/tweet.md) | 1 credit |
| `/v1/twitter/profile` | [X (Twitter): Profile](https://lurkapi.com/docs/twitter/profile.md) | 1 credit |
| `/v1/twitter/user-tweets` | [X (Twitter): User tweets](https://lurkapi.com/docs/twitter/user-tweets.md) | 1 credit |
| `/v1/threads/profile` | [Threads: Threads profile](https://lurkapi.com/docs/threads/profile.md) | 1 credit |
| `/v1/threads/user/posts` | [Threads: Threads account posts](https://lurkapi.com/docs/threads/user-posts.md) | 1 credit |
| `/v1/threads/post` | [Threads: Threads post](https://lurkapi.com/docs/threads/post.md) | 1 credit |
| `/v1/instagram/profile` | [Instagram: Profile](https://lurkapi.com/docs/instagram/profile.md) | 1 credit |
| `/v2/instagram/user/posts` | [Instagram: User posts](https://lurkapi.com/docs/instagram/user-posts.md) | 1 credit |
| `/v1/instagram/post` | [Instagram: Post](https://lurkapi.com/docs/instagram/post.md) | 1 credit |
| `/v2/instagram/post/comments` | [Instagram: Post comments](https://lurkapi.com/docs/instagram/post-comments.md) | 1 credit |
| `/v1/instagram/user/reels` | [Instagram: User reels](https://lurkapi.com/docs/instagram/user-reels.md) | 1 credit |
| `/v2/instagram/media/transcript` | [Instagram: Media transcript](https://lurkapi.com/docs/instagram/media-transcript.md) | 1 credit; 5 if speech-to-text runs |
| `/v1/linkedin/company` | [LinkedIn: LinkedIn company page](https://lurkapi.com/docs/linkedin/company.md) | 1 credit |
| `/v1/linkedin/company/posts` | [LinkedIn: LinkedIn company posts](https://lurkapi.com/docs/linkedin/company-posts.md) | 1 credit |
| `/v1/linkedin/ads/search` | [LinkedIn: Search LinkedIn ads](https://lurkapi.com/docs/linkedin/search-ads.md) | 1 credit |
| `/v1/linkedin/ad` | [LinkedIn: LinkedIn ad details](https://lurkapi.com/docs/linkedin/ad.md) | 1 credit |
| `/v1/linktree` | [Link-in-bio: Linktree page](https://lurkapi.com/docs/linkinbio/linktree.md) | 1 credit |
| `/v1/account/credit-balance` | [Account: Credit balance](https://lurkapi.com/docs/account/credit-balance.md) | free |

## What stays the same

- Paths, the `x-api-key` header, and `error` as a string.
- Allowed values in any case (`status=ACTIVE` works), an `r/` prefix on subreddit names, and trailing slashes.
- Unknown parameters such as `get_transcript` are ignored, blank parameters count as unset, and a repeated parameter uses its first value.
- Search companies accepts `country=ALL`.

## What's different

1. **Base URL** is `https://api.lurkapi.com`.
2. **Keys** start with `lk_live_`. `Authorization: Bearer <key>` also works.
3. **`credits_remaining`** is your real balance after the call.
4. **Status codes:** `402 insufficient_credits`; `429 rate_limited` or `429 signup_required`. A missing key is `401 missing_api_key` and a revoked key is `401 invalid_api_key`.
5. **Rate limit:** 50 requests per 10 seconds per account, with a `retry-after` header on `429`. High-volume accounts get 100; email [support@lurkapi.com](mailto:support@lurkapi.com).
6. **Error bodies** are `{ success: false, error, code, docs, issues? }`. Branch on `code`, not the `error` text. `502` and `503` responses don't include upstream details. [All codes](https://lurkapi.com/docs.md#errors).
7. **`trim` must be `true` or `false`** (any case). Anything else is `400 invalid_params`.
8. **Search companies `country`** must be `ALL` or a 2-letter country code.
9. **Only `GET`.** Other methods return `405 method_not_allowed`. Some providers also accept POST on search ads, company ads and post comments; send those as GET with query parameters.
10. **Charging:** A call is charged when it reached the platform, including `not_found` and other errors returned by the endpoint itself (e.g. a bad cursor). Free: parameter validation errors caught before the call, `401`/`402`/`429` rejections, and `5xx` failures (`500`/`502`/`503`). Cached responses cost the same as fresh ones. Anonymous tries follow the same rule.
11. **`cache_max_age` is ignored.** Each endpoint has its own cache time (see [Caching and freshness](https://lurkapi.com/docs.md#caching)).

### Fields we don't return

Reddit data comes from reddit.com's own pages, so fields those pages don't show are left out rather than guessed. Every Facebook endpoint and subreddit search return every key.

- [Subreddit posts](https://lurkapi.com/docs/reddit/subreddit-posts.md) (`posts[]`): no `downs`, `subreddit_subscribers`, `num_crossposts`, `edited`, `distinguished`, `archived`, `pinned`, `media`, `secure_media`, `media_embed`, `gilded`, `all_awardings`, `author_flair_text` or `link_flair_css_class`, and none of Reddit's moderator (`mod_reports`, `banned_by`…) or viewer-state (`saved`, `likes`, `clicked`…) fields.
- [Search Reddit](https://lurkapi.com/docs/reddit/search.md) (`posts[]`): only what the search page shows, so also no `selftext`, `selftext_html`, `url`, `url_overridden_by_dest`, `domain`, `is_self`, `is_video`, `preview`, `upvote_ratio`, `link_flair_text`, `stickied`, `locked` or `total_awards_received`. Pass the post's URL to [post comments](https://lurkapi.com/docs/reddit/post-comments.md) for the full post.
- [Post comments](https://lurkapi.com/docs/reddit/post-comments.md): `post` lacks the same fields as subreddit posts, plus `num_duplicates`; `comments[]` have no `downs`, `edited`, `distinguished`, `stickied`, `locked`, `controversiality`, `score_hidden`, `gilded`, `all_awardings`, `total_awards_received`, `author_flair_text` or `collapsed_reason`, nor moderator or viewer-state fields.
- [Subreddit details](https://lurkapi.com/docs/reddit/subreddit-details.md): no `subscribers`, `advertiser_category` or `submit_text`. Use `weekly_active_users` for size.

### Other response differences

- [Subreddit search](https://lurkapi.com/docs/reddit/subreddit-search.md) returns posts only.
- Facebook `watermarked_resized_image_url` is `""` rather than `null`, and `ig_verification` is `false` rather than `null`.
- [Company ads](https://lurkapi.com/docs/facebook/company-ads.md) defaults to `status=all`. Pass `status=active` for running ads only.
- `get_transcript` does nothing.

### Legacy mesmertools clients

- `/api/v1/...` paths still work: `https://api.lurkapi.com/api/v1/facebook/adLibrary/search/ads` is the same endpoint.
- `credits_remaining` used to be `-1`; errors used to be `{ error }` with different text ("missing required query param: query" is now "query: required"); a revoked key was `403`, now `401`.
- The Facebook ad endpoint and the Reddit endpoints used to read any `trim` value but `true` as false; now it's a `400`.

## Also included

- **Claude and MCP.** Every endpoint is also an MCP tool at `https://api.lurkapi.com/mcp`. [Connect it to Claude](https://lurkapi.com/docs.md#claude). Tool results skip nulls and empty lists to save tokens, and `trim` defaults to `true` where an endpoint has it.
- **Docs for agents.** [llms.txt](https://lurkapi.com/llms.txt), [openapi.json](https://lurkapi.com/openapi.json) and every docs page as markdown (add `.md` to the URL).
- **Pay per call**, from $0.199 per 1,000 credits, with no subscription. [Pricing](https://lurkapi.com/pricing.md).

[Get a free API key](https://lurkapi.com/login?next=/dashboard)