Use cases/AI agents
Social data API for AI agents
An agent that answers questions about what people say online needs live data, not a training cutoff. Each endpoint is a plain GET with a predictable JSON answer and stable error codes, which makes it a good tool for an agent to call.
Endpoints
The endpoints ai agents uses, each a GET request with your key in the x-api-key header.
| Endpoint | Request | Returns |
|---|---|---|
| SearchReddit | GET /v1/reddit/search?q=python | Posts across Reddit that match a search. |
| SearchYouTube | GET /v1/youtube/search?q=running | Videos and shorts that match a search; is_short tells them apart. |
| SearchThreads | GET /v1/threads/search?q=coffee | Posts that match a search: Threads' top results. |
| Video transcriptTikTok | GET /v1/tiktok/videos/transcript?video_id=7587811642650545421 | A video's captions, as one text and as timed segments. |
| Post commentsReddit | GET /v1/reddit/posts/comments?post_id=1wkziub | A post's comments in thread order, each with its depth. |
How it works
- 1Describe the toolsGenerate tool definitions from /openapi.json, or give the model /llms.txt to read.
- 2Call from your serverThe agent picks a tool; your server calls the API with your key, which never reaches the model.
- 3Let it pagepage.next_cursor goes back as cursor when the agent wants more results.
- 4Handle errorsEach error has a stable code and a retryable flag, so the agent knows when to try again.
Try it
Save your key and the base URL, then make the first calls:
export API_KEY="your-api-key"
export API_URL="https://api.socialparse.dev"
curl -H "x-api-key: $API_KEY" "$API_URL/v1/reddit/search?q=python"
curl -H "x-api-key: $API_KEY" "$API_URL/v1/youtube/search?q=running"
curl -H "x-api-key: $API_KEY" "$API_URL/v1/threads/search?q=coffee"Why it fits
- Every docs page is also Markdown at its URL plus .mdx, ready to paste into a prompt.
- One response envelope for every platform keeps tool definitions small.
- Errors cost nothing, so an agent's failed attempts don't spend credits.
FAQ
Is there an OpenAPI document?
Yes, at /openapi.json, with every endpoint's parameters, examples and responses.
Can the agent use my API key directly?
Keep the key on your server and call the API from your tool handler; anyone holding the key can spend your credits.
Which endpoints work best as tools?
Search and transcripts answer most questions; comments add what people think about a result.
Guides
Why one API for social dataProduct
Social Media Scraping vs an API: Build or Buy?FeaturedEngineering