# TrueScrape API

> Unified API for public social media data. One key, one schema, every platform.

## Billing rules an agent should know
- 1 credit = 1 request unless the endpoint says otherwise (see x-credit-cost in openapi.json).
- Failed requests are NEVER charged.
- Empty results are NEVER charged.
- Cache hits cost 0 credits. Add `cache_max_age=7d` to opt in.
- An invalid API key returns 401, not 402. A 402 always means the key is valid but the balance is not.

## Auth
Send your key in the `x-api-key` header.

## Long-running work
Do not poll synchronous endpoints in a loop. Use:
- POST /v1/jobs: async, no timeout ceiling
- POST /v1/jobs/batch: up to 500 targets in one call
- POST /v1/subscriptions: a webhook when data changes. Each check is billed at the endpoint's price (refunded if it fails or is empty), so omit interval_seconds to use the endpoint's suggested interval

## Machine-readable
- OpenAPI: https://api.truescrape.com/openapi.json
- This file: https://api.truescrape.com/llms.txt

## Endpoints

### amazon (4)

- `GET /v1/amazon/offers`: All seller offers for a product (3 credits, cacheable, batchable)
- `GET /v1/amazon/product`: Product details (3 credits, cacheable, batchable)
- `GET /v1/amazon/search`: Search results (3 credits, cacheable, batchable)
- `GET /v1/amazon/shop`: Amazon Shop page (1 credit, cacheable, batchable)

### apple-music (4)

- `GET /v1/apple-music/album`: Album details (1 credit, cacheable, batchable)
- `GET /v1/apple-music/artist`: Artist details (1 credit, cacheable, batchable)
- `GET /v1/apple-music/search`: Search (1 credit, cacheable, batchable)
- `GET /v1/apple-music/track`: Track details (1 credit, cacheable, batchable)

### bluesky (3)

- `GET /v1/bluesky/post`: Post (1 credit, cacheable, batchable)
- `GET /v1/bluesky/profile`: Profile (1 credit, cacheable, batchable)
- `GET /v1/bluesky/user/posts`: User posts (1 credit, cacheable, batchable)

### ebay (2)

- `GET /v1/ebay/product`: eBay listing details (1 credit, cacheable, batchable)
  - Pass either `product_id` or `url`.
- `GET /v1/ebay/search`: Search eBay listings (1 credit, cacheable, batchable)

### facebook (22)

- `GET /v1/facebook/ad-library/ad`: Ad details (1 credit, cacheable, batchable)
- `GET /v1/facebook/ad-library/ad-transcript`: Ad video transcript (1 credit, cacheable, batchable)
  - Pass exactly one of `id` or `url`.
- `GET /v1/facebook/ad-library/advertisers`: Find advertisers running ads (1 credit, cacheable, batchable)
- `GET /v1/facebook/ad-library/page-ads`: All ads for one advertiser (2 credits, cacheable, batchable)
- `GET /v1/facebook/ad-library/search`: Search the Meta Ad Library (2 credits, cacheable, batchable)
- `GET /v1/facebook/city-events`: Get the events of a city (1 credit, cacheable, batchable)
- `GET /v1/facebook/comment-replies`: Replies to a comment (1 credit, cacheable, batchable)
- `GET /v1/facebook/event`: Event details (1 credit, cacheable, batchable)
- `GET /v1/facebook/events/search`: Search public events (1 credit, cacheable, batchable)
- `GET /v1/facebook/group`: Public group info (1 credit, cacheable, batchable)
- `GET /v1/facebook/group-posts`: Public group posts (1 credit, cacheable, batchable)
- `GET /v1/facebook/marketplace/item`: Marketplace listing details (1 credit, cacheable, batchable)
- `GET /v1/facebook/marketplace/locations`: Find a Marketplace location (1 credit, cacheable, batchable)
- `GET /v1/facebook/marketplace/search`: Search Marketplace listings (1 credit, cacheable, batchable)
- `GET /v1/facebook/page-posts`: Public Page posts (1 credit, cacheable, batchable)
- `GET /v1/facebook/page-reels`: Public Page videos and reels (1 credit, cacheable, batchable)
- `GET /v1/facebook/post`: Single post, video, or reel (1 credit, cacheable, batchable)
- `GET /v1/facebook/post-comments`: Comments on a post (1 credit, cacheable, batchable)
- `GET /v1/facebook/post-transcript`: Video transcript (1 credit, cacheable, batchable)
- `GET /v1/facebook/profile`: Public Page profile (1 credit, cacheable, batchable)
- `GET /v1/facebook/profile-events`: Events on a Page (1 credit, cacheable, batchable)
- `GET /v1/facebook/profile-photos`: Photos on a Page (1 credit, cacheable, batchable)

### github (10)

- `GET /v1/github/repository`: Repository details (1 credit, cacheable, batchable)
- `GET /v1/github/trending/developers`: Trending developers (1 credit, cacheable)
- `GET /v1/github/trending/repositories`: Trending repositories (1 credit, cacheable)
- `GET /v1/github/user`: User or organisation profile (1 credit, cacheable, batchable)
  - Pass either `handle` or `url`.
- `GET /v1/github/user/activity`: Public activity (1 credit, cacheable, batchable)
  - Pass either `handle` or `url`.
- `GET /v1/github/user/contributions`: Contributions calendar (1 credit, cacheable, batchable)
  - Pass either `handle` or `url`.
- `GET /v1/github/user/followers`: Followers (1 credit, cacheable, batchable)
  - Pass either `handle` or `url`.
- `GET /v1/github/user/following`: Following (1 credit, cacheable, batchable)
  - Pass either `handle` or `url`.
- `GET /v1/github/user/pull-requests`: Pull requests by a user (1 credit, cacheable, batchable)
- `GET /v1/github/user/repositories`: User repositories (1 credit, cacheable, batchable)
  - Pass either `handle` or `url`.

### google (8)

- `GET /v1/google/ad-library/ad`: Ad details (1 credit, cacheable, batchable)
- `GET /v1/google/ad-library/advertiser-ads`: Ads run by an advertiser or domain (2 credits, cacheable, batchable)
  - Pass either `domain` or `advertiser_id`.
- `GET /v1/google/ad-library/advertisers`: Find advertisers in the Ads Transparency Centre (1 credit, cacheable, batchable)
- `GET /v1/google/jobs`: Google Jobs results (5 credits, cacheable, batchable)
- `GET /v1/google/maps-search`: Google Maps place search (5 credits, cacheable, batchable)
- `GET /v1/google/news`: Google News results (5 credits, cacheable, batchable)
- `GET /v1/google/search`: Web search results (1 credit, cacheable, batchable)
- `GET /v1/google/shopping`: Google Shopping results (5 credits, cacheable, batchable)

### identity (1)

- `GET /v1/find-social-profiles`: Find a creator's other social profiles (10 credits, cacheable, batchable)

### inference (1)

- `GET /v1/detect-age-gender`: Estimate age and gender from an image (1 credit, cacheable, batchable)

### instagram (19)

- `GET /v1/instagram/audio-reels`: Reels using a sound (1 credit, cacheable, batchable)
- `GET /v1/instagram/comment-replies`: Replies under one comment (1 credit, cacheable)
- `GET /v1/instagram/hashtag-posts`: Posts under a hashtag (1 credit, cacheable, batchable)
- `GET /v1/instagram/highlight`: Stories inside a highlight (1 credit, cacheable, batchable)
- `GET /v1/instagram/popular-search`: Top posts for a keyword (1 credit, cacheable, batchable)
- `GET /v1/instagram/post`: Post or reel details (1 credit, cacheable, batchable)
- `GET /v1/instagram/post-comments`: Comments on a post or reel (1 credit, cacheable, batchable)
- `GET /v1/instagram/profile`: Profile details (1 credit, cacheable, batchable)
- `GET /v1/instagram/profile-post-count`: Post count for a profile (1 credit, cacheable, batchable)
- `GET /v1/instagram/profile-search`: Search accounts (1 credit, cacheable, batchable)
- `GET /v1/instagram/reels-search`: Search reels by keyword (1 credit, cacheable, batchable)
- `GET /v1/instagram/search`: Search accounts, hashtags and places (1 credit, cacheable, batchable)
- `GET /v1/instagram/transcript`: Reel or video transcript (1 credit, cacheable, batchable)
- `GET /v1/instagram/trending-reels`: Reels trending on Explore (1 credit, cacheable)
- `GET /v1/instagram/user-embed`: Profile via the public embed card (1 credit, cacheable, batchable)
- `GET /v1/instagram/user-highlights`: Story highlight covers (1 credit, cacheable, batchable)
  - Pass either `handle` or `user_id`.
- `GET /v1/instagram/user-posts`: Posts and reels from a profile (1 credit, cacheable, batchable)
- `GET /v1/instagram/user-reels`: Reels from a profile (1 credit, cacheable, batchable)
  - Pass either `handle` or `user_id`.
- `GET /v1/instagram/user-tagged-posts`: Posts a profile is tagged in (1 credit, cacheable, batchable)
  - Pass either `handle` or `user_id`.

### kick (1)

- `GET /v1/kick/clip`: Clip (1 credit, cacheable, batchable)

### komi (1)

- `GET /v1/komi`: Komi page (1 credit, cacheable, batchable)

### kwai (3)

- `GET /v1/kwai/post`: Post (1 credit, cacheable, batchable)
- `GET /v1/kwai/profile`: Profile (1 credit, cacheable, batchable)
- `GET /v1/kwai/user/posts`: User posts (1 credit, cacheable, batchable)

### linkbio (1)

- `GET /v1/linkbio`: Lnk.Bio page (1 credit, cacheable, batchable)

### linkedin (8)

- `GET /v1/linkedin/ad`: Ad details (1 credit, cacheable, batchable)
- `GET /v1/linkedin/ads/search`: Search ads (1 credit, cacheable, batchable)
  - Pass `company`, `keyword`, or both. The Ad Library will not return an unfiltered archive.
- `GET /v1/linkedin/company`: Company page (1 credit, cacheable, batchable)
- `GET /v1/linkedin/company/posts`: Company posts (1 credit, cacheable, batchable)
- `GET /v1/linkedin/post`: Post details (1 credit, cacheable, batchable)
- `GET /v1/linkedin/post/transcript`: Post transcript (1 credit, cacheable, batchable)
- `GET /v1/linkedin/profile`: Person's profile (1 credit, cacheable, batchable)
- `GET /v1/linkedin/search/posts`: Search posts (1 credit, cacheable)

### linkme (1)

- `GET /v1/linkme`: LinkMe page (1 credit, cacheable, batchable)

### linktree (1)

- `GET /v1/linktree`: Linktree page (1 credit, cacheable, batchable)

### milkshake (1)

- `GET /v1/milkshake`: Milkshake page (1 credit, cacheable, batchable)

### pillar (1)

- `GET /v1/pillar`: Pillar page (1 credit, cacheable, batchable)

### pinterest (4)

- `GET /v1/pinterest/board`: Board and its pins (1 credit, cacheable, batchable)
- `GET /v1/pinterest/pin`: Pin details (1 credit, cacheable, batchable)
- `GET /v1/pinterest/search`: Search pins (1 credit, cacheable, batchable)
- `GET /v1/pinterest/user/boards`: Boards owned by a user (1 credit, cacheable, batchable)

### reddit (9)

- `GET /v1/reddit/post`: Post details (1 credit, cacheable, batchable)
- `GET /v1/reddit/post/comment/replies`: Comment replies (1 credit, cacheable, batchable)
- `GET /v1/reddit/post/comments`: Post comments (1 credit, cacheable, batchable)
- `GET /v1/reddit/post/transcript`: Video transcript (1 credit, cacheable, batchable)
- `GET /v1/reddit/search`: Search posts (1 credit, cacheable, batchable)
- `GET /v1/reddit/subreddit`: Subreddit posts (1 credit, cacheable, batchable)
- `GET /v1/reddit/subreddit/details`: Subreddit details (1 credit, cacheable, batchable)
- `GET /v1/reddit/user`: User profile (1 credit, cacheable, batchable)
- `GET /v1/reddit/user/posts`: User posts (1 credit, cacheable, batchable)

### redfin (4)

- `GET /v1/redfin/agent`: Real estate agent profile (1 credit, cacheable, batchable)
- `GET /v1/redfin/for-rent`: For-rent property details (1 credit, cacheable, batchable)
- `GET /v1/redfin/for-sale`: For-sale property details (1 credit, cacheable, batchable)
- `GET /v1/redfin/search`: Search Redfin listing results (1 credit, cacheable, batchable)

### rumble (5)

- `GET /v1/rumble/channel/videos`: Channel videos (1 credit, cacheable, batchable)
- `GET /v1/rumble/search`: Search videos (1 credit, cacheable, batchable)
- `GET /v1/rumble/video`: Video details (1 credit, cacheable, batchable)
- `GET /v1/rumble/video/comments`: Video comments (1 credit, cacheable, batchable)
- `GET /v1/rumble/video/transcript`: Video transcript (1 credit, cacheable, batchable)

### snapchat (3)

- `GET /v1/snapchat/profile`: User profile (1 credit, cacheable, batchable)
- `GET /v1/snapchat/spotlight`: Spotlight by link (1 credit, cacheable, batchable)
- `GET /v1/snapchat/spotlight/comments`: Spotlight comments by link (1 credit, cacheable, batchable)

### solo (1)

- `GET /v1/solo`: Solo page (1 credit, cacheable, batchable)

### soundcloud (3)

- `GET /v1/soundcloud/artist`: Artist profile (1 credit, cacheable, batchable)
- `GET /v1/soundcloud/artist/tracks`: Artist tracks (1 credit, cacheable, batchable)
- `GET /v1/soundcloud/track`: Track details (1 credit, cacheable, batchable)

### spotify (7)

- `GET /v1/spotify/album`: Album details (1 credit, cacheable, batchable)
- `GET /v1/spotify/artist`: Artist details (1 credit, cacheable, batchable)
- `GET /v1/spotify/playlist`: Playlist contents (1 credit, cacheable, batchable)
  - Pass exactly one of `id` or `url`.
- `GET /v1/spotify/podcast`: Podcast details (1 credit, cacheable, batchable)
- `GET /v1/spotify/podcast/episodes`: Podcast episodes (1 credit, cacheable, batchable)
- `GET /v1/spotify/search`: Search (1 credit, cacheable, batchable)
- `GET /v1/spotify/track`: Track details (1 credit, cacheable, batchable)

### taplink (1)

- `GET /v1/taplink`: Taplink page (1 credit, cacheable, batchable)

### telegram (3)

- `GET /v1/telegram/channel`: Channel (1 credit, cacheable, batchable)
- `GET /v1/telegram/channel-posts`: Channel posts (1 credit, cacheable, batchable)
- `GET /v1/telegram/post`: Post (1 credit, cacheable, batchable)

### threads (5)

- `GET /v1/threads/post`: Post (1 credit, cacheable, batchable)
- `GET /v1/threads/profile`: Profile (1 credit, cacheable, batchable)
- `GET /v1/threads/search`: Search posts by keyword (1 credit, cacheable, batchable)
- `GET /v1/threads/search/users`: Search users (1 credit, cacheable, batchable)
- `GET /v1/threads/user/posts`: User posts (1 credit, cacheable, batchable)

### tiktok (32)

- `GET /v1/tiktok/ad-library/ad`: One TikTok ad (1 credit, cacheable, batchable)
- `GET /v1/tiktok/ad-library/search`: Search the TikTok Ads Library (1 credit, cacheable)
- `GET /v1/tiktok/collection/videos`: Collection videos (1 credit, cacheable, batchable)
  - Pass either `url` or `collection_id`.
- `GET /v1/tiktok/comment-replies`: Replies to a comment (1 credit, cacheable, batchable)
- `GET /v1/tiktok/comments`: Comments on a video (1 credit, cacheable, batchable)
- `GET /v1/tiktok/creators/popular`: Popular creators (1 credit, cacheable, batchable)
- `GET /v1/tiktok/followers`: Accounts following a creator (1 credit, cacheable, batchable)
- `GET /v1/tiktok/following`: Accounts a creator follows (1 credit, cacheable, batchable)
- `GET /v1/tiktok/hashtag`: Hashtag details (1 credit, cacheable, batchable)
- `GET /v1/tiktok/hashtag-videos`: Videos using a hashtag (1 credit, cacheable, batchable)
- `GET /v1/tiktok/live`: Live stream info (1 credit, cacheable, batchable)
  - Pass either `handle` or `room_id`.
- `GET /v1/tiktok/playlist-videos`: Videos in a playlist (1 credit, cacheable, batchable)
- `GET /v1/tiktok/playlists`: A creator's playlists (1 credit, cacheable, batchable)
- `GET /v1/tiktok/product`: Product details (1 credit, cacheable, batchable)
- `GET /v1/tiktok/profile`: Profile details (1 credit, cacheable, batchable)
- `GET /v1/tiktok/profile/region`: Creator region (1 credit, cacheable, batchable)
  - Pass either `handle` or `url`.
- `GET /v1/tiktok/search/keyword`: Search videos by keyword (1 credit, cacheable, batchable)
- `GET /v1/tiktok/search/suggestions`: Search suggestions (1 credit, cacheable, batchable)
- `GET /v1/tiktok/search/top`: Top (blended) search (1 credit, cacheable, batchable)
- `GET /v1/tiktok/search/users`: Search creators (1 credit, cacheable, batchable)
- `GET /v1/tiktok/shop/product/reviews`: Product reviews (1 credit, cacheable, batchable)
- `GET /v1/tiktok/shop/products`: Seller's product catalogue (1 credit, cacheable, batchable)
- `GET /v1/tiktok/shop/search`: Search TikTok Shop (1 credit, cacheable, batchable)
- `GET /v1/tiktok/song`: Sound / song details (1 credit, cacheable, batchable)
- `GET /v1/tiktok/song-videos`: Videos using a sound (1 credit, cacheable, batchable)
- `GET /v1/tiktok/songs/popular`: Popular songs (1 credit, cacheable, batchable)
- `GET /v1/tiktok/transcript`: Video transcript (1 credit, cacheable, batchable)
- `GET /v1/tiktok/trending`: Trending feed (1 credit, cacheable, batchable)
- `GET /v1/tiktok/user-videos`: Videos posted by a creator (1 credit, cacheable, batchable)
- `GET /v1/tiktok/user/showcase`: Creator's product showcase (1 credit, cacheable, batchable)
- `GET /v1/tiktok/video`: Video or photo-post details (1 credit, cacheable, batchable)
- `GET /v1/tiktok/videos/popular`: Popular videos (1 credit, cacheable, batchable)

### truthsocial (3)

- `GET /v1/truthsocial/post`: Post (1 credit, cacheable, batchable)
- `GET /v1/truthsocial/profile`: Profile (1 credit, cacheable, batchable)
- `GET /v1/truthsocial/user/posts`: User posts (1 credit, cacheable, batchable)

### twitch (4)

- `GET /v1/twitch/clip`: Clip details (1 credit, cacheable, batchable)
- `GET /v1/twitch/profile`: Channel profile (1 credit, cacheable, batchable)
- `GET /v1/twitch/user/schedule`: Stream schedule (1 credit, cacheable, batchable)
- `GET /v1/twitch/user/videos`: Channel videos (1 credit, cacheable, batchable)

### twitter (6)

- `GET /v1/twitter/community`: Community details (1 credit, cacheable, batchable)
- `GET /v1/twitter/community/tweets`: Community posts (1 credit, cacheable, batchable)
- `GET /v1/twitter/profile`: Profile details (1 credit, cacheable, batchable)
- `GET /v1/twitter/tweet`: Post details (1 credit, cacheable, batchable)
- `GET /v1/twitter/tweet/transcript`: Post transcript (1 credit, cacheable, batchable)
- `GET /v1/twitter/user-tweets`: Recent posts from an account (1 credit, cacheable, batchable)

### walmart (4)

- `GET /v1/walmart/category`: Browse a Walmart category (3 credits, cacheable, batchable)
- `GET /v1/walmart/product`: Walmart product details (3 credits, cacheable, batchable)
- `GET /v1/walmart/reviews`: Walmart product reviews (3 credits, cacheable, batchable)
- `GET /v1/walmart/search`: Search Walmart (3 credits, cacheable, batchable)

### youtube (17)

- `GET /v1/youtube/channel`: Channel details (1 credit, cacheable, batchable)
- `GET /v1/youtube/channel-videos`: Channel videos (1 credit, cacheable, batchable)
- `GET /v1/youtube/channel/community-posts`: Channel community posts (1 credit, cacheable, batchable)
- `GET /v1/youtube/channel/lives`: Channel live streams (1 credit, cacheable, batchable)
- `GET /v1/youtube/channel/playlists`: Channel playlists (1 credit, cacheable, batchable)
- `GET /v1/youtube/channel/shorts`: Channel shorts (1 credit, cacheable, batchable)
- `GET /v1/youtube/community-post`: Community post details (1 credit, cacheable, batchable)
- `GET /v1/youtube/playlist`: Playlist contents (1 credit, cacheable, batchable)
- `GET /v1/youtube/search`: Search videos (1 credit, cacheable, batchable)
- `GET /v1/youtube/search/hashtag`: Search by hashtag (1 credit, cacheable, batchable)
- `GET /v1/youtube/search/typeahead`: Search typeahead (1 credit, cacheable, batchable)
- `GET /v1/youtube/shorts/trending`: Trending shorts (1 credit, cacheable, batchable)
- `GET /v1/youtube/transcript`: Video transcript (1 credit, cacheable, batchable)
- `GET /v1/youtube/video`: Video or Short details (1 credit, cacheable, batchable)
- `GET /v1/youtube/video/comment-replies`: Comment replies (1 credit, cacheable, batchable)
  - Pass either `cursor` (from `replyCursors` on /v1/youtube/video/comments), or both `url` and `comment_id`.
- `GET /v1/youtube/video/comments`: Video comments (1 credit, cacheable, batchable)
- `GET /v1/youtube/video/sponsors`: Video sponsors (inferred) (1 credit, cacheable, batchable)

### zillow (3)

- `GET /v1/zillow/agent`: Zillow agent profile (1 credit, cacheable, batchable)
- `GET /v1/zillow/property`: Zillow listing details (1 credit, cacheable, batchable)
  - Pass either `zpid` or `url`.
- `GET /v1/zillow/search`: Search Zillow listings by location (1 credit, cacheable, batchable)
  - Pass either `location` or `url`.