Quickstart

Before you start

Base URL: https://api.socialparse.dev. Every path starts with /v1/<platform>.
An API key: sign up, open API keys in the dashboard and choose New key. Copy it when it's shown: it isn't shown again. Your first workspace gets 100 free credits.
The x-api-key header: every call sends the key in it. Keep the key on your server, never in a browser or an app: anyone with it can spend your credits.

1. Save your API key

Keep the key and the base URL in environment variables, so they stay out of your code:

export API_KEY="your-api-key"
export API_URL="https://api.socialparse.dev"

2. Make your first request

Fetch the hot posts of r/Python:

curl -H "x-api-key: $API_KEY" "$API_URL/v1/reddit/subreddits/posts?subreddit=Python"

A 200 means the key works. Each call reads the live page, sometimes over several tries, so give it a generous timeout: a minute or two.

3. Read the response

Every success answers with the same envelope:

{
  "data": [
    {
      "id": "t3_1wkziub",
      "title": "What's everyone working on this week?",
      "subreddit": "Python",
      "score": 42,
      "comment_count": 17,
      "created_at": "2026-10-18T09:12:00Z"
    }
  ],
  "page": { "next_cursor": "t3_1wkx0ab", "has_more": true },
  "meta": {
    "platform": "reddit",
    "endpoint": "subreddit_posts",
    "params": { "subreddit": "Python", "sort": "hot" },
    "request_id": "req_1f8c2d3e4a5b6c7d",
    "api_version": "v1",
    "fetched_at": "2026-10-18T09:30:00Z",
    "cached": false
  }
}

data holds the result: here a list of posts.
page leads to the next page: send next_cursor as the cursor parameter. See Responses.
meta.request_id names this call. Log it, and quote it when you report a problem.
The X-Credits-Remaining header is your balance after the call. See Credits.

4. Handle common first-run failures

Status	Why	What to do
`401 UNAUTHORIZED`	The `x-api-key` header is missing, or the key is wrong.	Check the header and the variable.
`402 INSUFFICIENT_CREDITS`	The key's workspace is out of credits.	Buy more under Billing.
`403 LOGIN_REQUIRED`	The content is private, age-restricted or members-only.	Nothing: only public pages are read.
`429 RATE_LIMITED`	Too many calls this minute.	Wait as long as `Retry-After` says.
`503`	A brief outage, or the platform turned the request away.	Try again; see Errors.