# Social Fetch API - Query endpoints # Base URL: https://api.socialfetch.dev # Auth: x-api-key header (sfk_...) # Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json # Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json 3 documented Query operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported. ## POST /v1/query/validate Validate a Boolean query Credit cost: 0 credits. Failed requests are free. Docs: https://www.socialfetch.dev/docs/api/v1/query/validate/post.mdx curl "https://api.socialfetch.dev/v1/query/validate" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"from:nasa OR from:esa -filter:replies","syntax":"x","platforms":["twitter","reddit"],"since":"2026-11-01T00:00:00Z","maxCredits":20}' \ -X POST ## POST /v1/query/suggest Write a query from a description Credit cost: 0 credits. Failed requests are free. Docs: https://www.socialfetch.dev/docs/api/v1/query/suggest/post.mdx curl "https://api.socialfetch.dev/v1/query/suggest" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"brief":"Complaints about Lumora Foods: recalls, lawsuits and food poisoning, in English and Spanish. Not job ads.","examples":{"shouldMatch":["Lumora Foods is recalling its peanut butter after salmonella was found"],"shouldNotMatch":["Lumora Foods is hiring drivers in Leeds"]},"languages":["en","es"],"platforms":["twitter","reddit"],"maxCredits":30}' \ -X POST ## POST /v1/query/search Search with a Boolean query Credit cost: The searches it runs bill at their normal credit rates. The searches never spend more than maxCredits; what isn't used isn't charged. With sentiment, 1 credit per 10 posts given one, on top of maxCredits. With insights, 1 credit per 10 posts given them, on top of maxCredits. See meta.creditsCharged for the total. Docs: https://www.socialfetch.dev/docs/api/v1/query/search/post.mdx Parameters: - idempotency-key (required, string) - A key you choose for this search, such as a UUID. A retry with the same key and body returns the first response without charging again, for 24 hours. curl "https://api.socialfetch.dev/v1/query/search" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"(\"social fetch\" OR socialfetch) AND (api OR scraping) -hiring","platforms":["twitter","reddit"],"since":"2026-11-01T00:00:00Z","maxCredits":40,"noise":["jobs","giveaways"]}' \ -X POST