Migrating from another provider

The switch

1. 1Get a LurkAPI key. Keys start with lk_live_.
2. 2Change the base URL to https://api.lurkapi.com. Paths stay the same.
3. 3Keep 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 "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.

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. 1Base URL is https://api.lurkapi.com.
2. 2Keys start with lk_live_. Authorization: Bearer <key> also works.
3. 3credits_remaining is your real balance after the call.
4. 4Status 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. 5Rate limit: 50 requests per 10 seconds per account, with a retry-after header on 429. High-volume accounts get 100; email support@lurkapi.com.
6. 6Error 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.
7. 7trim must be true or false (any case). Anything else is 400 invalid_params.
8. 8Search companies country must be ALL or a 2-letter country code.
9. 9Only 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. 10Charging: 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. 11cache_max_age is ignored. Each endpoint has its own cache time (see Caching and freshness).

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 (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 (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 for the full post.
• Post comments: 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: no subscribers, advertiser_category or submit_text. Use weekly_active_users for size.

Other response differences

• Subreddit search returns posts only.
• Facebook watermarked_resized_image_url is "" rather than null, and ig_verification is false rather than null.
• Company ads 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. 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, 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.