Docs · apixstar

Authentication

Every /reddit/v1/* call must send an API key in the Authorization: Bearer header. Keys are created on the API keys page and shown once.

New API keys start with xstar_. Existing rdgo_live_ and rdgo_test_ keys remain valid. Query-string keys are not accepted. A revoked or unknown key returns INVALID_API_KEY and never reaches Reddit.

Header shape: Authorization: Bearer xstar_…

Resources

Identify Reddit objects in the path. Do not pass a Reddit URL, permalink, or uri query parameter.

Path	Returns
`GET /reddit/v1/r/{community}`	Community listing (hot)
`GET /reddit/v1/r/{community}/{sort}`	Sorted listing. `sort` is `new`, `hot`, `top`, `rising`, or `controversial`
`GET /reddit/v1/r/{community}/comments/{id}`	Post thread
`GET /reddit/v1/r/{community}/search`	Search inside a community (`q` required)
`GET /reddit/v1/u/{username}`	User profile
`GET /reddit/v1/u/{username}/submitted`	User’s posts
`GET /reddit/v1/posts/{id}`	Post by id (`t3_` prefix optional)
`GET /reddit/v1/comments/{id}`	Comment by id (`t1_` prefix optional)
`GET /reddit/v1/search`	Global search (`q` required)

Envelope and USD billing

Successful responses contain ok: true, data and meta. meta.method is feed, read or search; meta.path identifies the endpoint. meta.billing records the price snapshot and final USD charge. All money values are decimal strings with exactly four places.

Each read costs $0.0007. Feed costs $0.0007 per 20 returned posts, rounded up. Search counts posts plus comments and costs $0.0007 per 20 returned results, rounded up. Empty pages are free. Failures do not charge.

Feed/search default to limit=20; limit must be one integer from 1 to 100. We reserve the maximum cost before fetching and release the difference afterward. For limit=28, 28 results cost $0.0014; 3 results cost $0.0007. Each cursor page is billed separately. Read child comments do not add charges.

Every endpoint has independent pricing. The response includes the price version used. New accounts receive $0.5000; top-ups add the purchased USD amount. RPM counts HTTP requests, not billing units.

An optional X-Request-ID is scoped to your account. Reusing it returns HTTP 409 without another upstream request or charge; different parameters return IDEMPOTENCY_CONFLICT. Use a new ID for a new request.

{
  "ok": true,
  "data": {},
  "meta": {
    "method": "feed",
    "path": "/reddit/v1/r/typescript/new",
    "billing": {
      "pricingId": "community.new",
      "version": "usd-v1",
      "resultCount": 28,
      "billingUnits": 2,
      "unitPrice": "0.0007",
      "charged": "0.0014",
      "balanceRemaining": "9.4986",
      "currency": "USD"
    }
  }
}

Internal origin fields such as profile bindings are stripped and are not part of this contract.

GET /reddit/v1/r/{community}

List posts in a community. Add /{sort} for new, hot, top, rising, or controversial.

Query	Required	Meaning
`limit`	no	Page size, 1–100 (default 20)
`cursor`	no	Listing `after` token from a previous page
`minScore`	no	Drop posts below this score
`maxAgeHours`	no	Drop posts older than this many hours
`excludeAuthors`	no	Comma-separated author names to omit

Example — newest posts. Curl is only a request sketch.

GET https://console.apixstar.com/reddit/v1/r/typescript/new?limit=10
Authorization: Bearer xstar_…

curl "https://console.apixstar.com/reddit/v1/r/typescript/new?limit=10" \
  -H "Authorization: Bearer xstar_..."

GET /reddit/v1/u/{username}

Load a user profile. Use /submitted to list that user’s posts (same listing query params as a community feed).

Example — user profile.

GET https://console.apixstar.com/reddit/v1/u/spez
Authorization: Bearer xstar_…

curl "https://console.apixstar.com/reddit/v1/u/spez" \
  -H "Authorization: Bearer xstar_..."

GET /reddit/v1/posts/{id}

Load one post. GET /reddit/v1/comments/{id} loads a comment. GET /reddit/v1/r/{community}/comments/{id} loads a post thread in a community.

Query	Required	Meaning
`includeChildren`	no	When reading a post, include comment children unless set to false
`commentLimit`	no	Max comments on a post read (origin default 50, max 200)

Example — post thread.

GET https://console.apixstar.com/reddit/v1/r/typescript/comments/1abc2de
Authorization: Bearer xstar_…

curl "https://console.apixstar.com/reddit/v1/posts/1abc2de" \
  -H "Authorization: Bearer xstar_..."

GET /reddit/v1/search

Search posts (and optionally comments) globally. Scope to a community with GET /reddit/v1/r/{community}/search.

Query	Required	Meaning
`q`	yes	Search string
`sort`	no	`relevance`, `hot`, `top`, `new`, or `comments`
`timeRange`	no	`hour`, `day`, `week`, `month`, `year`, or `all` (alias `t`)
`limit`	no	Page size, 1–100 (default 20)
`cursor`	no	Listing `after` token from a previous page
`includeComments`	no	If true, also search comment listings

Example — community search.

GET https://console.apixstar.com/reddit/v1/r/typescript/search?q=bun&limit=10
Authorization: Bearer xstar_…

curl "https://console.apixstar.com/reddit/v1/r/typescript/search?q=bun&limit=10" \
  -H "Authorization: Bearer xstar_..."

Rate limits

Limits are per account, not per key, and follow the highest paid top-up on the account. Signup-only accounts use the Free tier. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Tier. Exceeding the cap returns RATE_LIMITED with Retry-After.

Plan	Requests / minute
Free (no paid pack)	30
Starter	60
Pro	300
Scale	1200

Errors

Failures use ok: false and an error.code. They do not debit the wallet. Rate-limit responses may include Retry-After.

INVALID_API_KEY: Missing Authorization: Bearer header, key has an unsupported prefix, or the key was revoked. HTTP 401.
INSUFFICIENT_BALANCE: The account cannot cover the maximum USD reservation. The origin is not called. HTTP 402.
RATE_LIMITED: The account exceeded its plan’s requests-per-minute cap (Free 30, Starter 60, Pro 300, Scale 1200). HTTP 429.
INVALID_PATH: The path is not a supported resource, or search is missing q. HTTP 400.
REDDIT_RATE_LIMITED: The Reddit origin returned HTTP 429. HTTP 429.
REDDIT_TIMEOUT: The origin did not respond before the Worker timeout (25s). HTTP 504.
REDDIT_HTTP_ERROR: The origin returned a non-success Reddit HTTP error (including blocked pages). HTTP 502 unless the origin status is forwarded.
REDDIT_UNAVAILABLE: The origin is down, busy, or cooling down. HTTP 502 or 503.

API reference