Reddit Scraper API
A REST API for Reddit data. Start a scrape for posts, comments, subreddits or user profiles, wait for it to finish and download the results as JSON, CSV, XML or Excel, without running your own scraper or applying for Reddit API access.
A Reddit API alternative for data collection
Every kind of Reddit data
Posts, comments, subreddits and user profiles, from up to 9 keyword searches or a Reddit URL. Pick exactly the fields you need (GET /v1/fields lists them all).
Filters you would build yourself
Sort keyword searches by hot, top, new or relevance, limit post searches to the past hour, day, week, month or year, include or exclude NSFW content, and collect up to 10,000 items per scrape.
No scraping infrastructure
RedScraper runs every scrape in a managed environment: no Reddit app or OAuth credentials, proxies, headless browsers or retry logic on your side.
Results in the format you need
Page through rows as JSON, or download a whole scrape as JSON Lines, CSV, XML or Excel with one request.
Built for reliable integrations
Wait up to 25 seconds per request for a scrape to finish instead of polling in a tight loop, retry safely with an Idempotency-Key, and handle one consistent error format.
Same account as the dashboard
Scrapes started through the API appear in your dashboard history and use the same plan compute hours, so you can mix the no-code scraper and code freely.
Overview
| Item | Value |
|---|---|
Base URL | https://api.redscraper.io/v1 |
OpenAPI 3.1 | https://api.redscraper.io/v1/openapi.json |
MCP server | https://api.redscraper.io/mcp |
Authentication | Authorization: Bearer YOUR_API_KEY |
Version header | X-RedScraper-Api-Version: 1 |
Conventions
- JSON request and response bodies with camelCase keys. Send Content-Type: application/json with every body.
- Timestamps are ISO-8601 in UTC with a Z suffix, for example 2026-11-09T14:03:12Z.
- Money is a string with two decimals plus a currency field, for example "amount": "50.00", "currency": "usd".
- Trailing slashes are optional on every route.
- Unknown body fields are rejected with 400, so a typo such as dry_run never silently does something else.
- Every response carries the header X-RedScraper-Api-Version: 1. Authenticated responses are sent with Cache-Control: no-store.
Quickstart
REDSCRAPER_API_KEY environment variable, then start a scrape, wait for it and download the results:export REDSCRAPER_API_KEY="YOUR_API_KEY"
# 1. Start a scrape. The Idempotency-Key makes retries safe.
curl -X POST "https://api.redscraper.io/v1/scrapes" \
-H "Authorization: Bearer $REDSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: weekly-ml-report-2026-11-09" \
-d '{
"searches": ["machine learning", "ai agents"],
"dataTypes": {
"posts": ["title", "content", "url", "upvotes", "numComments"],
"comments": true
},
"sort": "top",
"time": "week",
"includeNsfw": false,
"maxItems": 200
}'
# -> 201 Created: { "id": 1287, "status": "running", ... }
# 2. Wait for it. Each call waits up to 25 seconds; repeat while "status" is "running".
# If the response has a Retry-After header (server busy), sleep that many seconds first.
curl -i "https://api.redscraper.io/v1/scrapes/1287?wait=25" \
-H "Authorization: Bearer $REDSCRAPER_API_KEY"
# 3a. Read the results as JSON pages (up to 1000 rows per page)...
curl "https://api.redscraper.io/v1/scrapes/1287/results?offset=0&limit=1000" \
-H "Authorization: Bearer $REDSCRAPER_API_KEY"
# 3b. ...or download every row as a file: format=jsonl, csv, xml or xlsx
curl -OJ "https://api.redscraper.io/v1/scrapes/1287/results?format=csv" \
-H "Authorization: Bearer $REDSCRAPER_API_KEY"
# -> saves redscraper-1287.csvAuthentication
Authorization header (preferred) or the X-API-Key header. Dashboard session tokens are not accepted.Authorization: Bearer YOUR_API_KEY # or X-API-Key: YOUR_API_KEY
A missing, unknown or revoked key returns 401:
// 401 Unauthorized
// WWW-Authenticate: Bearer realm="RedScraper API"
{
"error": {
"code": "unauthenticated",
"message": "Dashboard session tokens are not accepted; create an API key in the dashboard"
}
}Access levels & scopes
| Access level | What it can do |
|---|---|
Standard | Start and cancel scrapes, read results, usage and billing, update your profile and contact support. Cannot change billing or manage API keys. |
Read-only | View scrapes, results, usage, your profile and billing. Cannot start scrapes or change anything. |
Full access | Everything in Standard, plus changing or canceling your subscription and creating or revoking API keys. |
| Scope | Allows | Read-only | Standard | Full |
|---|---|---|---|---|
scrapes:read | List scrapes, read their status and results, and read usage. | |||
scrapes:write | Start and cancel scrapes (consumes plan compute hours). | - | ||
account:read | Read the account profile. | |||
account:write | Update the account profile and contact support. | - | ||
billing:read | Read the subscription and transactions. | |||
billing:write | Start checkout, change or cancel the subscription (can charge the card on file). | - | - | |
keys:read | List API keys (never their secrets). | - | - | |
keys:write | Create and revoke API keys. | - | - |
A call that needs a scope the key does not have returns 403 insufficient_scope, with the missing scope in details.requiredScope.
Errors
{
"error": {
"code": "validation_error", // stable: use it in your code
"message": "The request is invalid.", // for people; may be reworded
"details": { ... } // only on some errors
}
}// 400 Bad Request
{
"error": {
"code": "validation_error",
"message": "The request is invalid.",
"details": {
"maxItems": ["Must be between 1 and 10000."],
"dataTypes.posts": [
"Unknown field(s): likes. Allowed: title, content, url, subreddit, username, numComments, upvotes, media, flair, upvoteRatio, mediaType, nsfw."
]
}
}
}| code | HTTP | Meaning |
|---|---|---|
validation_error | 400 | A field is missing or invalid. details maps each field to a list of messages. |
invalid_json | 400 | The request body is not valid JSON. |
unauthenticated | 401 | Missing, unknown or revoked API key, or a dashboard session token was sent instead of an API key. |
subscription_required | 402 | An active subscription is needed (starting scrapes, changing or canceling a plan). |
compute_limit_reached | 402 | Your plan's compute hours for the current billing period are used up. details.usage shows the numbers and periodEnd, when they renew. Upgrade your plan to keep scraping before then. |
insufficient_scope | 403 | The API key does not have the scope this call needs. details.requiredScope names it. |
not_found | 404 | The endpoint or resource does not exist, or it belongs to another account. |
method_not_allowed | 405 | The HTTP method is not supported on this endpoint. The Allow header lists the valid ones. |
conflict | 409 | The resource is in the wrong state: the scrape is not running or not completed, already subscribed, same plan, already canceled or revoked, or the API key limit is reached. |
payload_too_large | 413 | The request body is larger than 2.5 MB. |
unsupported_media_type | 415 | The request body is not sent as application/json. |
rate_limited | 429 | Too many requests. Wait for the number of seconds in the Retry-After header. |
concurrent_limit_reached | 429 | Your plan's number of scrapes running at once is reached (Basic 2, Professional 3, Enterprise 5). Wait for one to finish, then start the next. |
internal_error | 500 | Unexpected server error. Retry later; contact support if it persists. |
upstream_error | 502 | The scraping or payment provider failed or could not be reached. Nothing was changed; retry shortly. |
Errors from the scraping or payment provider never include their raw responses. 5xx responses and 429 are safe to retry after a short wait; for creating scrapes, retry with the same Idempotency-Key.
Pagination
page (from 1) and pageSize (1 to 100, default 20) and return the items in data with totals in pagination. Scrape results use offset and limit instead.GET /v1/scrapes?page=2&pageSize=50
{
"data": [ ... ],
"pagination": { "page": 2, "pageSize": 50, "total": 134, "totalPages": 3 }
}Idempotency
POST /v1/scrapes without starting a second scrape, send an Idempotency-Key header.POST /v1/scrapes Idempotency-Key: weekly-ml-report-2026-11-09 -> 201 Created (a new scrape is started) POST /v1/scrapes (retry, same key) Idempotency-Key: weekly-ml-report-2026-11-09 -> 200 OK Idempotent-Replayed: true (the same scrape, nothing new is started)
- Use a new unique value (for example a UUID) for each scrape you mean to start, and send the same value again when you retry it.
- Keys belong to your account and do not expire. A key you already used always returns the scrape it created, even if the request body is different.
- Up to 255 characters.
- In MCP, pass
idempotency_keyto thecreate_scrapetool.
Dashboard-only actions
Endpoint reference
Each endpoint shows the scope it needs. Besides the errors listed, any authenticated endpoint can return 401 unauthenticated, 403 insufficient_scope, 429 rate_limited and 500 internal_error; requests with a body can also return 400 invalid_json or 415 unsupported_media_type. The complete schemas are in the OpenAPI document.
Scrapes
Start, monitor and cancel scrapes. Scrapes started from the dashboard, the API and MCP all appear here and in your dashboard history.
/v1/scrapes
Start a scrape. It runs through the same pipeline as the dashboard and appears in your dashboard history. The call returns right away with status "running"; poll GET /v1/scrapes/{id}?wait=25 until it finishes, then download the results. Running scrapes use your plan's compute hours.
Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
searches | string[] | searches or url | - | 1 to 9 keyword searches, each non-empty and at most 200 characters. Send either searches or url, not both. |
url | string | searches or url | - | A Reddit URL to scrape: http(s) on reddit.com, any *.reddit.com subdomain, or redd.it. |
dataTypes | object | Yes | - | At least one of posts, comments, subreddits, users. Set a type to true for every field, or to a list of field keys (see below and GET /v1/fields). |
sort | string | No | "none" | none, hot, top, new or relevance. Keyword searches only: with posts every sort is allowed; with comments but no posts, hot is not; otherwise only none. |
time | string | No | "all" | all, hour, day, week, month or year. Only for keyword searches that include posts; otherwise it must be all. |
includeNsfw | boolean | No | true | Include NSFW content. |
maxItems | integer | No | 50 | Maximum number of items to collect, 1 to 10,000. |
format | string | No | "json" | json, csv, xml or excel. Preferred export format saved with the scrape for the dashboard; API responses are not affected. |
Headers
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
Idempotency-Key | string | No | - | Up to 255 characters. Sending a key you already used returns the scrape created with it (200, Idempotent-Replayed: true) instead of starting a new one. |
Field keys
Use these keys in dataTypes (set a data type to true for every field, or to a list of keys) and in the results fields parameter.
posts
comments
subreddits
users
Request
POST /v1/scrapes
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: weekly-ml-report-2026-11-09
Content-Type: application/json
{
"searches": ["machine learning", "ai agents"],
"dataTypes": {
"posts": ["title", "content", "url", "upvotes", "numComments"],
"comments": true
},
"sort": "top",
"time": "week",
"includeNsfw": false,
"maxItems": 200
}Response
// 201 Created (Location: /v1/scrapes/1287)
{
"id": 1287,
"runId": "HG7ML7M8z78YcAPEB",
"status": "running",
"source": "api",
"createdAt": "2026-11-09T14:03:12Z",
"completedAt": null,
"computeSeconds": null,
"itemCount": 0,
"itemLimit": 200,
"accuracy": null,
"request": {
"searches": ["machine learning", "ai agents"],
"url": null,
"dataTypes": {
"posts": ["title", "content", "url", "numComments", "upvotes"],
"comments": true
},
"sort": "top",
"time": "week",
"includeNsfw": false,
"maxItems": 200,
"format": "json"
},
"links": {
"self": "/v1/scrapes/1287",
"results": "/v1/scrapes/1287/results"
}
}Error Responses
- 400 — validation_error: a missing, unknown or invalid field, or a sort/time that is not available for this request
- 402 — subscription_required: you need an active subscription to start scrapes
- 402 — compute_limit_reached: your plan's compute hours for this billing period are used up (details.usage says when they renew)
- 429 — concurrent_limit_reached: your plan's number of scrapes running at once is reached; wait for one to finish
- 502 — upstream_error: the scraping provider did not start the run; retry with the same Idempotency-Key
Code Example
import os
import requests
response = requests.post(
"https://api.redscraper.io/v1/scrapes",
headers={
"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}",
"Idempotency-Key": "weekly-ml-report-2026-11-09",
},
json={
"searches": ["machine learning", "ai agents"],
"dataTypes": {
"posts": ["title", "content", "url", "upvotes", "numComments"],
"comments": True
},
"sort": "top",
"time": "week",
"includeNsfw": False,
"maxItems": 200
},
timeout=30,
)
print(response.status_code, response.json())/v1/scrapes
Your scrapes from the dashboard, the API and MCP, newest first, without results. Listing does not contact the scraping provider, so the status of a running scrape can be a few seconds old; fetch the scrape itself for a fresh status.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | integer | No | 1 | Page number, 1 or more. A page past the end returns an empty data array. |
pageSize | integer | No | 20 | Items per page, 1 to 100. |
status | string | No | - | running, completed, failed or canceled. |
source | string | No | - | Where the scrape was started: dashboard, api or mcp. |
Response
// 200 OK
{
"data": [
{
"id": 1287,
"runId": "HG7ML7M8z78YcAPEB",
"status": "completed",
"source": "api",
"createdAt": "2026-11-09T14:03:12Z",
"completedAt": "2026-11-09T14:09:47Z",
"computeSeconds": 395.4,
"itemCount": 200,
"itemLimit": 200,
"accuracy": 100,
"request": {
"searches": ["machine learning", "ai agents"],
"url": null,
"dataTypes": {
"posts": ["title", "content", "url", "numComments", "upvotes"],
"comments": true
},
"sort": "top",
"time": "week",
"includeNsfw": false,
"maxItems": 200,
"format": "json"
},
"links": {
"self": "/v1/scrapes/1287",
"results": "/v1/scrapes/1287/results"
}
}
],
"pagination": { "page": 1, "pageSize": 20, "total": 42, "totalPages": 3 }
}Error Responses
- 400 — validation_error: invalid page, pageSize, status or source
Code Example
import os
import requests
response = requests.get(
"https://api.redscraper.io/v1/scrapes",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
params={"status": "completed", "page": 1, "pageSize": 20},
timeout=30,
)
print(response.status_code, response.json())/v1/scrapes/{id}
One scrape. The status of a running scrape is refreshed from the scraping provider (at most every 10 seconds). Use wait to long-poll instead of calling in a tight loop; the response always arrives within 25 seconds, so set your HTTP client timeout to about 40 seconds. When the server is busy it answers at once, with a Retry-After header: wait that many seconds before polling again. status is running, completed, failed or canceled (unknown for very old records).
Path and query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id | integer | string | Yes | - | The scrape id, or the runId of the scrape. |
wait | integer | No | 0 | Seconds (0 to 25) to wait for a running scrape to finish. The response comes back as soon as it finishes or the time is up; it can also come back earlier, and while the server is busy it comes back at once with a Retry-After header. |
Response
// 200 OK
{
"id": 1287,
"runId": "HG7ML7M8z78YcAPEB",
"status": "completed",
"source": "api",
"createdAt": "2026-11-09T14:03:12Z",
"completedAt": "2026-11-09T14:09:47Z",
"computeSeconds": 395.4,
"itemCount": 200,
"itemLimit": 200,
"accuracy": 100,
"request": {
"searches": ["machine learning", "ai agents"],
"url": null,
"dataTypes": {
"posts": ["title", "content", "url", "numComments", "upvotes"],
"comments": true
},
"sort": "top",
"time": "week",
"includeNsfw": false,
"maxItems": 200,
"format": "json"
},
"links": {
"self": "/v1/scrapes/1287",
"results": "/v1/scrapes/1287/results"
}
}Error Responses
- 400 — validation_error: wait is not an integer from 0 to 25
- 404 — not_found: no scrape with this id in your account
Code Example
import os
import requests
response = requests.get(
"https://api.redscraper.io/v1/scrapes/1287",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
params={"wait": 25},
timeout=40,
)
print(response.status_code, response.json())/v1/scrapes/{id}/cancel
Abort a running scrape and mark it canceled. No request body.
Response
// 200 OK
{
"id": 1287,
"runId": "HG7ML7M8z78YcAPEB",
"status": "canceled",
"source": "api",
"createdAt": "2026-11-09T14:03:12Z",
"completedAt": "2026-11-09T14:05:30Z",
"computeSeconds": 0,
"itemCount": 0,
"itemLimit": 200,
"accuracy": null,
"request": {
"searches": ["machine learning", "ai agents"],
"url": null,
"dataTypes": {
"posts": ["title", "content", "url", "numComments", "upvotes"],
"comments": true
},
"sort": "top",
"time": "week",
"includeNsfw": false,
"maxItems": 200,
"format": "json"
},
"links": {
"self": "/v1/scrapes/1287",
"results": "/v1/scrapes/1287/results"
}
}Error Responses
- 404 — not_found: no scrape with this id in your account
- 409 — conflict: the scrape is not running (details.status holds its current status)
- 502 — upstream_error: the scraping provider could not cancel it right now; try again
Code Example
import os
import requests
response = requests.post(
"https://api.redscraper.io/v1/scrapes/1287/cancel",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())Results
Read the rows of a completed scrape as JSON pages, or download them as JSON Lines, CSV, XML or Excel.
/v1/scrapes/{id}/results
The rows of a completed scrape. format=json (the default) returns a page of rows; jsonl, csv, xml and xlsx return every row as a file named redscraper-<id>.<ext> (offset and limit are ignored). Every row has type and id, then the selected fields. type is the label the scraping provider uses: post or submission, comment, subreddit or community, or user. To get one data type, use the type parameter, which matches both labels, rather than comparing row.type yourself. CSV and Excel columns are the field keys, nested values are written as JSON text, and cells that look like spreadsheet formulas are neutralized.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
format | string | No | "json" | json (a page of rows), or jsonl, csv, xml or xlsx for a file with every row. excel is accepted as an alias of xlsx. |
offset | integer | No | 0 | Rows to skip (json only). |
limit | integer | No | 100 | Rows per page, 1 to 1000 (json only). |
type | string | No | - | Only rows of one data type: posts, comments, subreddits or users (matches both labels a data type can have, for example subreddit and community). |
fields | string | No | - | Comma-separated field keys to keep, for example title,url,upvotes. type and id are always kept. Works with every format. |
Response
// 200 OK (format=json)
{
"data": [
{
"type": "post",
"id": "t3_1gq2x7k",
"title": "What are you using to evaluate AI agents?",
"content": "We are comparing a few evaluation harnesses for tool-using agents...",
"url": "https://www.reddit.com/r/MachineLearning/comments/1gq2x7k/what_are_you_using_to_evaluate_ai_agents/",
"numComments": 87,
"upvotes": 412
},
{
"type": "comment",
"id": "t1_lx3k9qz",
"username": "gradient_ascent",
"communityName": "MachineLearning",
"body": "We log every tool call and replay the traces against a fixed task set.",
"createdAt": "2026-11-08T19:22:41.000Z",
"upvotes": 56,
"numberOfreplies": 4,
"url": "https://www.reddit.com/r/MachineLearning/comments/1gq2x7k/comment/lx3k9qz/"
}
],
"pagination": { "offset": 0, "limit": 100, "total": 200 }
}Error Responses
- 400 — validation_error: unknown format, type or field key, or limit/offset out of range
- 404 — not_found: no scrape with this id in your account
- 409 — conflict: the scrape is not completed yet, or it failed or was canceled (details.status)
Code Example
import os
import requests
url = "https://api.redscraper.io/v1/scrapes/1287/results"
headers = {"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"}
# A page of JSON rows
page = requests.get(url, headers=headers, params={"offset": 0, "limit": 100}, timeout=30).json()
print(page["pagination"]["total"], "rows")
# Every post as an Excel file with three columns (plus type and id)
response = requests.get(
url,
headers=headers,
params={"format": "xlsx", "type": "posts", "fields": "title,url,upvotes"},
timeout=60,
)
response.raise_for_status()
with open("redscraper-1287.xlsx", "wb") as f:
f.write(response.content)Account
Your profile and the API key in use.
/v1/me
Your profile, a subscription summary and the API key making the call, with its scopes and access level.
Response
// 200 OK
{
"id": 4821,
"email": "ada@example.com",
"firstName": "Ada",
"lastName": "Lovelace",
"dateJoined": "2025-03-14T09:26:53Z",
"subscription": {
"status": "active",
"plan": "Professional",
"priceMonthly": "100.00",
"currency": "usd",
"renewalDate": "2026-12-01T00:00:00Z",
"endDate": "2026-12-01T00:00:00Z",
"pendingPlanChange": null
},
"apiKey": {
"id": 17,
"name": "Production server",
"scopes": [
"scrapes:read",
"scrapes:write",
"account:read",
"account:write",
"billing:read"
],
"preset": "standard"
}
}Code Example
import os
import requests
response = requests.get(
"https://api.redscraper.io/v1/me",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())/v1/me
Change your first and/or last name. Returns the updated account. Password changes and account deletion are only available in the dashboard.
Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
firstName | string | No | - | Non-empty, at most 150 characters. |
lastName | string | null | No | - | At most 150 characters. An empty string or null clears it. |
Request
PATCH /v1/me
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{ "firstName": "Ada", "lastName": "Lovelace" }Response
// 200 OK
{
"id": 4821,
"email": "ada@example.com",
"firstName": "Ada",
"lastName": "Lovelace",
"dateJoined": "2025-03-14T09:26:53Z",
"subscription": {
"status": "active",
"plan": "Professional",
"priceMonthly": "100.00",
"currency": "usd",
"renewalDate": "2026-12-01T00:00:00Z",
"endDate": "2026-12-01T00:00:00Z",
"pendingPlanChange": null
},
"apiKey": {
"id": 17,
"name": "Production server",
"scopes": [
"scrapes:read",
"scrapes:write",
"account:read",
"account:write",
"billing:read"
],
"preset": "standard"
}
}Error Responses
- 400 — validation_error: an empty body, an unknown field, an empty firstName or a name that is too long
Code Example
import os
import requests
response = requests.patch(
"https://api.redscraper.io/v1/me",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
json={"firstName": "Ada", "lastName": "Lovelace"},
timeout=30,
)
print(response.status_code, response.json())Subscription & Billing
Read and manage your subscription. Changes use the same rules and payment flow as the dashboard and need the billing:write scope (Full access keys).
/v1/subscription
Your plan and its state. status is active, pending_cancellation or none. renewalDate is the next automatic renewal (null when it will not renew); endDate is the end of the current billing period; pendingPlanChange shows a scheduled downgrade.
Response
// 200 OK
{
"status": "active",
"plan": "Professional",
"priceMonthly": "100.00",
"currency": "usd",
"renewalDate": "2026-12-01T00:00:00Z",
"endDate": "2026-12-01T00:00:00Z",
"pendingPlanChange": null
}Code Example
import os
import requests
response = requests.get(
"https://api.redscraper.io/v1/subscription",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())/v1/subscription/checkout
Create a Stripe Checkout page for a new subscription. A person has to open checkoutUrl in a browser to pay; this call does not charge anything. If you already have a subscription, use POST /v1/subscription/change instead.
Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
plan | string | Yes | - | basic, professional or enterprise (plan id or name, case-insensitive). See GET /v1/plans. |
Request
POST /v1/subscription/checkout
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{ "plan": "professional" }Response
// 200 OK
{
"checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4...",
"plan": "Professional"
}Error Responses
- 400 — validation_error: unknown plan
- 409 — conflict: you already have a subscription (details.currentPlan); change it instead
- 502 — upstream_error: the payment provider could not start checkout
Code Example
import os
import requests
response = requests.post(
"https://api.redscraper.io/v1/subscription/checkout",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
json={"plan": "professional"},
timeout=30,
)
print(response.status_code, response.json())/v1/subscription/change
Switch plans with the same rules as the dashboard. An upgrade takes effect immediately and charges the card on file the prorated difference right away. A downgrade takes effect at the end of the billing period. Send dryRun: true first to see exactly what will happen; the real call also returns the updated subscription.
Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
plan | string | Yes | - | basic, professional or enterprise (plan id or name, case-insensitive). See GET /v1/plans. |
dryRun | boolean | No | false | true returns a preview of what would happen without changing anything or charging. |
Request
POST /v1/subscription/change
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{ "plan": "enterprise", "dryRun": true }Response
// 200 OK (dryRun: true)
{
"currentPlan": "Professional",
"newPlan": "Enterprise",
"direction": "upgrade",
"effective": "immediate",
"effectiveDate": null,
"priceDifference": "50.00",
"currency": "usd",
"message": "Upgrading from Professional to Enterprise takes effect immediately. The card on file is charged the prorated difference for the rest of the current billing period right away, then $150.00/month.",
"dryRun": true
}Error Responses
- 400 — validation_error: unknown plan, or dryRun is not a boolean
- 402 — subscription_required: there is no active subscription to change
- 409 — conflict: you are already on this plan, or a cancellation is pending
- 502 — upstream_error: the payment provider did not confirm the change
Code Example
import os
import requests
response = requests.post(
"https://api.redscraper.io/v1/subscription/change",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
json={"plan": "enterprise", "dryRun": True},
timeout=30,
)
print(response.status_code, response.json())/v1/subscription/cancel
Cancel at the end of the current billing period. You keep access until then and are not charged again. The body is optional; send dryRun: true to preview.
Body (optional)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
dryRun | boolean | No | false | true returns a preview of what would happen without changing anything or charging. |
Request
POST /v1/subscription/cancel
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{}Response
// 200 OK
{
"currentPlan": "Professional",
"effectiveDate": "2026-12-01T00:00:00Z",
"message": "Your Professional subscription will be canceled at the end of the current billing period (2026-12-01). You keep access until then and will not be charged again.",
"dryRun": false,
"subscription": {
"status": "pending_cancellation",
"plan": "Professional",
"priceMonthly": "100.00",
"currency": "usd",
"renewalDate": null,
"endDate": "2026-12-01T00:00:00Z",
"pendingPlanChange": null
}
}Error Responses
- 400 — validation_error: dryRun is not a boolean, or an unknown field
- 402 — subscription_required: there is no subscription to cancel
- 409 — conflict: the subscription is already scheduled to cancel
- 502 — upstream_error: the payment provider did not confirm the cancellation
Code Example
import os
import requests
response = requests.post(
"https://api.redscraper.io/v1/subscription/cancel",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
json={"dryRun": True},
timeout=30,
)
print(response.status_code, response.json())/v1/transactions
Your payments, newest first.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | integer | No | 1 | Page number, 1 or more. A page past the end returns an empty data array. |
pageSize | integer | No | 20 | Items per page, 1 to 100. |
Response
// 200 OK
{
"data": [
{
"transactionNumber": "100245",
"date": "2026-11-01T00:00:12Z",
"paymentMethod": "Stripe",
"amount": "100.00",
"currency": "usd",
"plan": "Professional"
}
],
"pagination": { "page": 1, "pageSize": 20, "total": 8, "totalPages": 1 }
}Error Responses
- 400 — validation_error: page or pageSize is out of range
Code Example
import os
import requests
response = requests.get(
"https://api.redscraper.io/v1/transactions",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
params={"page": 1},
timeout=30,
)
print(response.status_code, response.json())Usage
Run statistics and compute hours.
/v1/usage
The numbers from your dashboard overview plus your plan's compute-hour allowance for the current billing period. totalComputeTimeUsed, monthlyUsage and plan values are in hours; averageRunTime is in seconds; successRate is items scraped divided by items requested, in percent. plan.computeHoursUsed counts every scrape started in the period, including timed-out, canceled and running ones (only failures in under a minute are free), and is the number checked when you start a scrape: at plan.computeHoursRemaining 0, new scrapes are refused until plan.periodEnd. plan.concurrentScrapeLimit is how many scrapes can run at once.
Response
// 200 OK
{
"totalRuns": 42,
"successfulRuns": 39,
"failedRuns": 3,
"totalComputeTimeUsed": 6.84,
"totalItemsScraped": 18250,
"totalItemsRequested": 19400,
"successRate": 94.1,
"averageRunTime": 412.6,
"topDataTypes": [
{ "type": "Posts", "count": 31, "percentage": 62 },
{ "type": "Comments", "count": 19, "percentage": 38 }
],
"recentActivity": [
{
"date": "2026-11-09",
"runs": 3,
"items": 1200,
"status": "success"
}
],
"monthlyUsage": { "currentMonth": 1.92 },
"plan": {
"name": "Professional",
"computeHoursIncluded": 50,
"computeHoursUsed": 1.92,
"computeHoursRemaining": 48.08,
"periodStart": "2026-11-01T08:30:00Z",
"periodEnd": "2026-12-01T08:30:00Z",
"concurrentScrapeLimit": 3
}
}Code Example
import os
import requests
response = requests.get(
"https://api.redscraper.io/v1/usage",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())API Keys
List, create and revoke API keys. Needs the keys:read and keys:write scopes (Full access keys).
/v1/keys
Your API keys, active and revoked, newest first. Secrets are never returned. current is true for the key making the call.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | integer | No | 1 | Page number, 1 or more. A page past the end returns an empty data array. |
pageSize | integer | No | 20 | Items per page, 1 to 100. |
Response
// 200 OK
{
"data": [
{
"id": 18,
"name": "Reporting job",
"scopes": ["scrapes:read", "account:read", "billing:read"],
"preset": "read_only",
"createdAt": "2026-11-09T15:12:04Z",
"lastUsedAt": null,
"revoked": false,
"revokedAt": null,
"current": false
},
{
"id": 17,
"name": "Production server",
"scopes": [
"scrapes:read",
"scrapes:write",
"account:read",
"account:write",
"billing:read"
],
"preset": "standard",
"createdAt": "2026-10-02T08:41:55Z",
"lastUsedAt": "2026-11-09T15:10:31Z",
"revoked": false,
"revokedAt": null,
"current": true
}
],
"pagination": { "page": 1, "pageSize": 20, "total": 2, "totalPages": 1 }
}Error Responses
- 400 — validation_error: page or pageSize is out of range
Code Example
import os
import requests
response = requests.get(
"https://api.redscraper.io/v1/keys",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())/v1/keys
Create an API key. The secret is returned only in this response. A key cannot create a key with scopes it does not have itself, and an account can have at most 10 active keys.
Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | No | "API Key" | A label for the key, at most 100 characters. |
preset | string | No | "standard" | Access level: read_only, standard or full. |
scopes | string[] | No | - | An explicit list of scopes instead of a preset. Send preset or scopes, not both. |
Request
POST /v1/keys
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{ "name": "Reporting job", "preset": "read_only" }Response
// 201 Created
{
"id": 18,
"name": "Reporting job",
"scopes": ["scrapes:read", "account:read", "billing:read"],
"preset": "read_only",
"createdAt": "2026-11-09T15:12:04Z",
"lastUsedAt": null,
"revoked": false,
"revokedAt": null,
"current": false,
"secret": "<64-character secret, returned only once>",
"message": "Save this key securely; it will not be shown again."
}Error Responses
- 400 — validation_error: unknown preset or scope, both preset and scopes sent, or an invalid name
- 403 — insufficient_scope: the new key would have scopes the calling key lacks (details.missingScopes)
- 409 — conflict: you already have 10 active keys; revoke one first
Code Example
import os
import requests
response = requests.post(
"https://api.redscraper.io/v1/keys",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
json={"name": "Reporting job", "preset": "read_only"},
timeout=30,
)
print(response.status_code, response.json())/v1/keys/{id}
Revoke one of your API keys. It stops working immediately. A key can revoke itself. Returns the revoked key.
Response
// 200 OK
{
"id": 18,
"name": "Reporting job",
"scopes": ["scrapes:read", "account:read", "billing:read"],
"preset": "read_only",
"createdAt": "2026-11-09T15:12:04Z",
"lastUsedAt": null,
"revoked": true,
"revokedAt": "2026-11-09T16:00:00Z",
"current": false
}Error Responses
- 404 — not_found: no key with this id in your account
- 409 — conflict: the key is already revoked
Code Example
import os
import requests
response = requests.delete(
"https://api.redscraper.io/v1/keys/18",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
timeout=30,
)
print(response.status_code, response.json())Support
Contact the RedScraper team.
/v1/support
Send a message to RedScraper support from your account. Replies go to your account email address.
Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
message | string | Yes | - | 1 to 5,000 characters. |
subject | string | No | "Support request" | At most 200 characters. |
Request
POST /v1/support
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"subject": "Export question",
"message": "How do I export comments only?"
}Response
// 202 Accepted
{ "status": "sent" }Error Responses
- 400 — validation_error: message is missing or too long, or an unknown field
- 502 — upstream_error: the message could not be sent; try again later
Code Example
import os
import requests
response = requests.post(
"https://api.redscraper.io/v1/support",
headers={"Authorization": f"Bearer {os.environ['REDSCRAPER_API_KEY']}"},
json={
"subject": "Export question",
"message": "How do I export comments only?"
},
timeout=30,
)
print(response.status_code, response.json())Public
Discovery endpoints. No API key needed.
/v1
Links to this documentation, the OpenAPI document and the MCP server.
Response
// 200 OK
{
"name": "RedScraper API",
"version": "1",
"docs": "https://www.redscraper.io/dashboard/api-management",
"openapi": "https://api.redscraper.io/v1/openapi.json",
"mcp": "https://api.redscraper.io/mcp"
}Code Example
import requests
response = requests.get(
"https://api.redscraper.io/v1",
timeout=30,
)
print(response.status_code, response.json())/v1/openapi.json
The OpenAPI 3.1 description of every v1 endpoint, with request and response schemas, the scope each operation needs, and error responses. Import it into Postman or Insomnia, or generate a typed client with a tool such as openapi-generator.
Code Example
import requests
response = requests.get(
"https://api.redscraper.io/v1/openapi.json",
timeout=30,
)
response.raise_for_status()
with open("redscraper-openapi.json", "wb") as f:
f.write(response.content)/v1/plans
Subscription plans with monthly price and included compute hours.
Response
// 200 OK
[
{
"id": "basic",
"name": "Basic",
"priceMonthly": "50.00",
"currency": "usd",
"computeHoursIncluded": 10,
"features": ["Unlimited data output", "10 hours compute time"]
},
{
"id": "professional",
"name": "Professional",
"priceMonthly": "100.00",
"currency": "usd",
"computeHoursIncluded": 50,
"features": ["Unlimited data output", "50 hours compute time", "Priority support"]
},
{
"id": "enterprise",
"name": "Enterprise",
"priceMonthly": "150.00",
"currency": "usd",
"computeHoursIncluded": 100,
"features": [
"Unlimited data output",
"100 hours compute time",
"Priority support",
"Dedicated account manager"
]
}
]Code Example
import requests
response = requests.get(
"https://api.redscraper.io/v1/plans",
timeout=30,
)
print(response.status_code, response.json())/v1/fields
The field keys you can select for each data type, with their dashboard labels, plus the allowed sort, time, format and maxItems values and their rules.
Field keys
Use these keys in dataTypes (set a data type to true for every field, or to a list of keys) and in the results fields parameter.
posts
comments
subreddits
users
Response
// 200 OK (abbreviated)
{
"dataTypes": {
"posts": [
{ "key": "title", "label": "Title", "description": "Post title." },
{ "key": "content", "label": "Content", "description": "Post body text." },
...
],
"comments": [ ... ],
"subreddits": [ ... ],
"users": [ ... ]
},
"sort": {
"values": ["none", "hot", "top", "new", "relevance"],
"default": "none",
"rules": "Sorting only applies to keyword searches (not url). ...",
"availability": {
"url": ["none"],
"searchesWithPosts": ["none", "hot", "top", "new", "relevance"],
"searchesWithCommentsNoPosts": ["none", "top", "new", "relevance"],
"searchesOther": ["none"]
}
},
"time": {
"values": ["all", "hour", "day", "week", "month", "year"],
"default": "all",
"rules": "The time filter only applies to keyword searches that include posts; ..."
},
"formats": { "values": ["json", "csv", "xml", "excel"], "default": "json" },
"maxItems": { "min": 1, "max": 10000, "default": 50 },
"searches": { "maxCount": 9, "maxLength": 200 },
"url": { "allowedHosts": ["reddit.com", "*.reddit.com", "redd.it"] },
"includeNsfw": { "default": true }
}Code Example
import requests
response = requests.get(
"https://api.redscraper.io/v1/fields",
timeout=30,
)
print(response.status_code, response.json())Frequently asked questions
Is this an alternative to the official Reddit API?
For collecting public Reddit data, yes. Instead of registering a Reddit app, handling OAuth and writing your own pagination and rate-limit logic, you describe what you want (keywords or a Reddit URL, data types, fields and filters) and RedScraper collects it for you. The API only reads public posts, comments, subreddits and profiles: it cannot post, comment or vote on Reddit.
How much does the API cost?
Creating API keys is free on every account. Starting scrapes needs an active subscription, and scrapes started through the API use the same plan compute hours as scrapes started in the dashboard. See pricing for the plans.
What are the rate limits?
1,000 requests per hour per API key, shared between the REST API and the MCP server. Over the limit you get 429 rate_limited with a Retry-After header that says how many seconds to wait.
Can AI agents use the API?
Yes. The RedScraper MCP server gives Claude, Cursor, VS Code and other MCP clients the same features as tools, with the same API keys.
Is there a machine-readable specification?
Yes. The OpenAPI 3.1 document describes every endpoint, schema, required scope and error, and can be used to generate a client in your language. It is public; no API key is needed to download it.

Start building with Reddit data
Create an API key in a minute and run your first scrape with the quickstart above.