# FetchFox API documentation Structured public social data for developer applications and agents. Canonical: https://fetchfox.net/docs ## Authentication REST base URL: https://api.fetchfox.net. Send your project key in the x-access-key header. GET uses query parameters; POST uses JSON. Do not put access_key in URLs; that legacy parameter is deprecated because URLs can leak through history and logs. Keep keys on your server. Rotation immediately invalidates the old key. MCP: https://mcp.fetchfox.net/mcp (Streamable HTTP), Authorization: Bearer YOUR_KEY or x-access-key: YOUR_KEY. REST and MCP share the same project balance. OAuth is not enabled for this deployment. ## Credits and pricing 20 free credits per calendar month (UTC). No credit card required. There is no separate monthly request-attempt allowance. Operational rate, concurrency and daily safety limits apply. Failed processing uses no credits. - Starter: $29 per month for 12,000 credits. - Growth: $39 per month for 30,000 credits. - Pro: $69 per month for 60,000 credits. - Scale: $99 per month for 90,000 credits. - Credit pack: $25 once for 3,000 credits. Published plans do not guarantee checkout is enabled. Check https://fetchfox.net/pricing for current availability, billing-country prices and taxes. Unused monthly credits do not roll over. - YouTube video or channel stats: 1 per request. - YouTube search or channel/playlist videos: 1 up to 50 returned; 2 above 50. - YouTube transcript, including bulk: 1 per successful video. - Instagram profile or post stats: 1 per request. - Instagram posts or reels: 1 per 20 returned items. - TikTok video stats or channel videos: 1 per request. - YouTube, TikTok, Instagram or Facebook comments: 1 per 50 returned comments. - TikTok search: 1 per 50 returned results. ## Public trial limits - Free-plan rate: 40 authenticated requests per minute per project. - Concurrent extraction: 2 per project; 4 across the public trial service. - Daily extraction attempts: 50 per project; 100 across the public trial service; resets at 00:00 UTC. - Monthly attempts: No separate monthly attempt allowance; successful work uses the 20 monthly credits. - Anonymous preview: 10 attempts per public IP per hour; 20 uncached retrieval attempts per UTC day across visitors. - /youtube/transcript/bulk: default 1–5 URLs, maximum returned 5 URLs. POST only; sequential items under a shared deadline; inspect every item. - /youtube/comments: default 20, maximum returned 100. One batch; no cursor. - /tiktok/comments: default 20, maximum returned 100. Keep the same video with the returned cursor. - /youtube/search: default 20, maximum returned 100. One bounded batch. - /youtube/videos: default 20, maximum returned 100. Channel or playlist; one bounded batch. - /instagram/comments: default 10, maximum returned 100. Keep the same post and sort order with the returned cursor. - /facebook/comments: default 10, maximum returned 100. Keep the same post with the returned cursor. - /instagram/channel-posts: default 12, maximum returned 100. Use the returned cursor for the next page. - /instagram/channel-reels: default 12, maximum returned 100. Use the returned cursor for the next page. - /tiktok/channel-videos: default 30, maximum returned 100. Use the returned cursor for the next page. - /tiktok/search: default 10, maximum returned 100. Default request requires 1 available credit; larger limits require 1 per 20 requested results. For operations exposing country, use an uppercase two-letter country code (for example US, IN or GB). Recognized country-name aliases map to AU, BR, CA, CN, FR, DE, GR, HK, IT, IN, IL, JP, MX, NL, PL, PT, RO, SG, KR, ES, SE, TR, GB and US. The parser also accepts other two-letter codes; provider exit availability is not guaranteed or independently certified for every country. Omit country for the default routing. Country is not a language-selection option. ## Error catalog - HTTP 400: invalid_input (or validation error). Retry: No. Correct the URL, input name or value. - HTTP 401: Missing key; code may be absent. Retry: No. Send x-access-key for REST or a Bearer key for MCP. - HTTP 403: Invalid key or insufficient_credits. Retry: No. Check the key and available balance; do not repeat unchanged requests. - HTTP 404 / 422: content_unavailable, content_restricted, no_transcript. Retry: No. Check source access or choose another resource; follow retryable when present. - HTTP 422: transcript_not_ready, media_not_ready. Retry: Not immediately. Wait for a live/upcoming recording to become available. - HTTP 429: rate_limited (or capacity message). Retry: Yes, after delay. Honor Retry-After; both rate and daily/concurrency limits can apply. - HTTP 500 / 502 / 503 / 504: operation_failed or service failure. Retry: Bounded retries. Retry with backoff and a stopping limit; follow retryable when present. - HTTP 502 / 503: instagram_login_required, instagram_media_unavailable, instagram_views_unavailable. Retry: Bounded retries. A signed-in browser view does not establish anonymous API access. Extraction error body: success=false, message, errorCode, retryable. Auth/admission/validation errors may omit errorCode and retryable. Follow HTTP status and Retry-After. ## Errors, limits and freshness Check HTTP status and the success field before consuming data. Validation errors and failed processing use no credits. Successful requests use the operation’s normal credit rate, including cached responses. x-credits-used reports the charge. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset report the rate window. Respect Retry-After on HTTP 429 and bound retries. Missing or private content must not be retried indefinitely. Results are public source snapshots and may be cached. Authenticated free-tier YouTube transcripts can be cached for five minutes; the anonymous, truncated homepage preview has a separate 15-minute cache. Optional fields may be unavailable; missing values are not zero. Store source URLs and retrieval times. No latency or uptime SLA is published. Use only content you are permitted to access and process.