{"openapi":"3.1.0","info":{"title":"RedScraper API","version":"1.0.0","description":"Programmatic access to everything in the RedScraper dashboard: start Reddit scrapes, poll them, download results (JSON, JSON Lines, CSV, XML, Excel), and manage usage, billing, API keys and support.\n\n**Authentication.** Create an API key in the dashboard (API management) and send it as `Authorization: Bearer <key>` (preferred) or `X-API-Key: <key>`. Dashboard session tokens are not accepted. Each key has scopes (scrapes:read, scrapes:write, account:read, account:write, billing:read, billing:write, keys:read, keys:write); presets: read_only, standard (default), full.\n\n**Errors** use one envelope: `{\"error\": {\"code\", \"message\", \"details\"?}}`.\n\n**Pagination.** List endpoints take `page` (default 1) and `pageSize` (1-100, default 20) and return `{\"data\": [...], \"pagination\": {page, pageSize, total, totalPages}}`.\n\n**Conventions.** JSON with camelCase keys, ISO-8601 UTC timestamps, money as strings with two decimals plus `currency`. Trailing slashes are optional. Every response carries `X-RedScraper-Api-Version: 1`.\n\n**MCP.** The same capabilities are available to AI agents as a remote MCP server at https://api.redscraper.io/mcp.\n\nLogin, registration, password changes, account deletion and session management are only available in the dashboard.","contact":{"name":"RedScraper support","url":"https://www.redscraper.io/reddit-scraper-api/"}},"servers":[{"url":"https://api.redscraper.io","description":"Production"}],"externalDocs":{"description":"API & MCP documentation","url":"https://www.redscraper.io/reddit-scraper-api/"},"tags":[{"name":"Meta","description":"Discovery endpoints (no authentication)."},{"name":"Scrapes","description":"Start, monitor and cancel scrapes; download results."},{"name":"Account","description":"Profile and usage."},{"name":"Billing","description":"Plans, subscription and payments."},{"name":"API keys","description":"Manage API keys."},{"name":"Support","description":"Contact RedScraper support."}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/v1":{"get":{"operationId":"getApiIndex","summary":"API index","description":"Links to the documentation, the OpenAPI document and the MCP server.","tags":["Meta"],"security":[],"responses":{"200":{"description":"API index.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"OpenAPI document","description":"This OpenAPI 3.1 document.","tags":["Meta"],"security":[],"responses":{"200":{"description":"The OpenAPI document.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAPIDocument"}}}}}}},"/v1/plans":{"get":{"operationId":"listPlans","summary":"List plans","description":"Subscription plans with monthly price and included compute hours.","tags":["Billing"],"security":[],"responses":{"200":{"description":"Plans.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}}}}}}}},"/v1/fields":{"get":{"operationId":"listDataFields","summary":"List data fields","description":"Field keys selectable per data type (posts, comments, subreddits, users) and the allowed sort/time values. Use the keys in dataTypes when creating a scrape and in the results fields parameter.","tags":["Scrapes"],"security":[],"responses":{"200":{"description":"Field catalog.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldCatalog"}}}}}}},"/v1/me":{"get":{"operationId":"getAccount","summary":"Get account","description":"Profile, subscription summary and the calling API key.\n\nRequired scope: `account:read`.","tags":["Account"],"x-required-scope":"account:read","responses":{"200":{"description":"Account.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"operationId":"updateAccount","summary":"Update profile","description":"Change the first and/or last name.\n\nRequired scope: `account:write`.","tags":["Account"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountRequest"},"example":{"firstName":"Ada","lastName":"Lovelace"}}}},"x-required-scope":"account:write","responses":{"200":{"description":"Updated account.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/subscription":{"get":{"operationId":"getSubscription","summary":"Get subscription","description":"Current plan, status, renewal and any scheduled plan change.\n\nRequired scope: `billing:read`.","tags":["Billing"],"x-required-scope":"billing:read","responses":{"200":{"description":"Subscription.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/subscription/checkout":{"post":{"operationId":"createCheckout","summary":"Start subscription checkout","description":"Creates a Stripe Checkout page for a new subscription. A human must open checkoutUrl in a browser to pay; nothing is charged by this call. Returns 409 when a subscription already exists (use /v1/subscription/change).\n\nRequired scope: `billing:write`.","tags":["Billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"},"example":{"plan":"professional"}}}},"x-required-scope":"billing:write","responses":{"200":{"description":"Checkout session.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/v1/subscription/change":{"post":{"operationId":"changePlan","summary":"Change plan","description":"Upgrades take effect immediately and charge the card on file the prorated difference right away; downgrades take effect at the end of the billing period. Send dryRun: true first to preview. 402 without a subscription; 409 for the current plan or a pending cancellation.\n\nRequired scope: `billing:write`.","tags":["Billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePlanRequest"},"example":{"plan":"enterprise","dryRun":true}}}},"x-required-scope":"billing:write","responses":{"200":{"description":"Plan change (or its preview when dryRun is true).","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanChange"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/v1/subscription/cancel":{"post":{"operationId":"cancelSubscription","summary":"Cancel subscription","description":"Cancels at the end of the current billing period (access continues until then). Send dryRun: true to preview. 402 without a subscription; 409 when cancellation is already scheduled.\n\nRequired scope: `billing:write`.","tags":["Billing"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionRequest"},"example":{"dryRun":true}}}},"x-required-scope":"billing:write","responses":{"200":{"description":"Cancellation (or its preview).","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCancellation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/v1/transactions":{"get":{"operationId":"listTransactions","summary":"List transactions","description":"Payments, newest first.\n\nRequired scope: `billing:read`.","tags":["Billing"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"x-required-scope":"billing:read","responses":{"200":{"description":"Transactions.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/usage":{"get":{"operationId":"getUsage","summary":"Get usage","description":"Dashboard analytics plus the compute hours used and remaining in the current billing period (the same numbers enforced when a scrape starts).\n\nRequired scope: `scrapes:read`.","tags":["Account"],"x-required-scope":"scrapes:read","responses":{"200":{"description":"Usage.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/scrapes":{"get":{"operationId":"listScrapes","summary":"List scrapes","description":"Scrapes started from the dashboard, the API or MCP, newest first. Does not contact the scraping provider; fetch a single scrape for a fresh status.\n\nRequired scope: `scrapes:read`.","tags":["Scrapes"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["running","completed","failed","canceled"]}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["dashboard","api","mcp"]}}],"x-required-scope":"scrapes:read","responses":{"200":{"description":"Scrapes.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapeList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createScrape","summary":"Create scrape","description":"Starts a scrape (uses plan compute hours). Returns immediately with status running; poll GET /v1/scrapes/{id}?wait=25 until it is completed, then download the results. Send an Idempotency-Key header to make retries safe. Refused with 402 compute_limit_reached when the plan's compute hours for the billing period are used up (see GET /v1/usage), and with 429 concurrent_limit_reached when the plan's number of scrapes running at once is reached.\n\nRequired scope: `scrapes:write`.","tags":["Scrapes"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScrapeRequest"},"example":{"searches":["machine learning","ai agents"],"dataTypes":{"posts":["title","content","url","upvotes","numComments"],"comments":true},"sort":"top","time":"week","includeNsfw":false,"maxItems":200}}}},"x-required-scope":"scrapes:write","responses":{"200":{"description":"Idempotent replay: the scrape created earlier with this Idempotency-Key.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scrape"}}}},"201":{"description":"Scrape started.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"},"Location":{"$ref":"#/components/headers/Location"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scrape"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/ScrapePaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/ScrapeLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/v1/scrapes/{id}":{"get":{"operationId":"getScrape","summary":"Get scrape","description":"One scrape. A running scrape is refreshed from the scraping provider (at most every 10 seconds). wait=1..25 long-polls until the scrape finishes or the wait ends; the response always comes within 25 seconds. When the server is busy it answers at once with a Retry-After header: wait that many seconds before polling again.\n\nRequired scope: `scrapes:read`.","tags":["Scrapes"],"parameters":[{"$ref":"#/components/parameters/ScrapeId"},{"name":"wait","in":"query","required":false,"description":"Seconds to wait for a running scrape to finish (an upper bound: the server may answer earlier, see Retry-After).","schema":{"type":"integer","minimum":0,"maximum":25,"default":0}}],"x-required-scope":"scrapes:read","responses":{"200":{"description":"Scrape.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"},"Retry-After":{"$ref":"#/components/headers/PollRetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scrape"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/scrapes/{id}/cancel":{"post":{"operationId":"cancelScrape","summary":"Cancel scrape","description":"Aborts a running scrape. 409 when it is not running.\n\nRequired scope: `scrapes:write`.","tags":["Scrapes"],"parameters":[{"$ref":"#/components/parameters/ScrapeId"}],"x-required-scope":"scrapes:write","responses":{"200":{"description":"Canceled scrape.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scrape"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/v1/scrapes/{id}/results":{"get":{"operationId":"getScrapeResults","summary":"Get scrape results","description":"Results of a completed scrape (409 with details.status otherwise). format=json (default) returns a page of rows; jsonl, csv, xml and xlsx return every row as a file download named redscraper-<id>.<ext> (offset/limit are ignored). CSV/XLSX columns are the field keys; nested values are JSON text; spreadsheet formulas are neutralized.\n\nRequired scope: `scrapes:read`.","tags":["Scrapes"],"parameters":[{"$ref":"#/components/parameters/ScrapeId"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","jsonl","csv","xml","xlsx","excel"],"default":"json"},"description":"Response format ('excel' is an alias of xlsx)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"type","in":"query","required":false,"description":"Only rows of this data type.","schema":{"type":"string","enum":["posts","comments","subreddits","users"]}},{"name":"fields","in":"query","required":false,"description":"Comma-separated field keys to keep (type and id are always kept).","schema":{"type":"string"},"example":"title,url,upvotes"}],"x-required-scope":"scrapes:read","responses":{"200":{"description":"Results.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"},"Content-Disposition":{"$ref":"#/components/headers/ContentDisposition"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapeResultsPage"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"application/xml":{"schema":{"type":"string"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/keys":{"get":{"operationId":"listApiKeys","summary":"List API keys","description":"Keys of this account (secrets are never returned).\n\nRequired scope: `keys:read`.","tags":["API keys"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"x-required-scope":"keys:read","responses":{"200":{"description":"API keys.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"operationId":"createApiKey","summary":"Create API key","description":"Creates a key and returns its secret once. At most 10 active keys (409). The new key cannot have scopes the calling key lacks (403).\n\nRequired scope: `keys:write`.","tags":["API keys"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"},"example":{"name":"Reporting job","preset":"read_only"}}}},"x-required-scope":"keys:write","responses":{"201":{"description":"Created key, including its secret.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedApiKey"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke API key","description":"Revokes a key of this account (the calling key included). 409 when it is already revoked.\n\nRequired scope: `keys:write`.","tags":["API keys"],"parameters":[{"$ref":"#/components/parameters/KeyId"}],"x-required-scope":"keys:write","responses":{"200":{"description":"Revoked key.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/support":{"post":{"operationId":"contactSupport","summary":"Contact support","description":"Sends a message to RedScraper support from this account.\n\nRequired scope: `account:write`.","tags":["Support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportRequest"},"example":{"subject":"Export question","message":"How do I export comments only?"}}}},"x-required-scope":"account:write","responses":{"202":{"description":"Message sent.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportAccepted"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer <API key> (preferred)."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"X-API-Key: <API key>."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthenticated","insufficient_scope","forbidden","not_found","validation_error","invalid_json","subscription_required","compute_limit_reached","concurrent_limit_reached","conflict","method_not_allowed","unsupported_media_type","payload_too_large","not_acceptable","rate_limited","upstream_error","internal_error"]},"message":{"type":"string","description":"Human-readable explanation."},"details":{"type":"object","additionalProperties":true,"description":"Optional. validation_error: field -> [messages]; insufficient_scope: {requiredScope}; conflict: e.g. {status}; rate_limited: {retryAfterSeconds}; compute_limit_reached: {usage: {periodStart, periodEnd, usedSeconds, includedSeconds, remainingSeconds}}; concurrent_limit_reached: {running, limit}."}}}},"description":"Error envelope used by every v1 error response."},"PagePagination":{"type":"object","required":["page","pageSize","total","totalPages"],"properties":{"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}}},"OffsetPagination":{"type":"object","required":["offset","limit","total"],"properties":{"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":1000},"total":{"type":"integer","minimum":0,"description":"Rows matching the type filter."}}},"ApiIndex":{"type":"object","required":["name","version","docs","openapi","mcp"],"properties":{"name":{"type":"string"},"version":{"type":"string","const":"1"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"}}},"Plan":{"type":"object","required":["id","name","priceMonthly","currency","computeHoursIncluded","features"],"properties":{"id":{"type":"string","enum":["basic","professional","enterprise"]},"name":{"type":"string","enum":["Basic","Professional","Enterprise"]},"priceMonthly":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount with two decimals."},"currency":{"type":"string","const":"usd"},"computeHoursIncluded":{"type":"integer"},"features":{"type":"array","items":{"type":"string"}}}},"FieldInfo":{"type":"object","required":["key","label","description"],"properties":{"key":{"type":"string","description":"Field key used in requests and results."},"label":{"type":"string","description":"Label shown in the dashboard."},"description":{"type":"string"}}},"FieldCatalog":{"type":"object","required":["dataTypes","sort","time","formats","maxItems","searches","url","includeNsfw"],"properties":{"dataTypes":{"type":"object","required":["posts","comments","subreddits","users"],"properties":{"posts":{"type":"array","items":{"$ref":"#/components/schemas/FieldInfo"}},"comments":{"type":"array","items":{"$ref":"#/components/schemas/FieldInfo"}},"subreddits":{"type":"array","items":{"$ref":"#/components/schemas/FieldInfo"}},"users":{"type":"array","items":{"$ref":"#/components/schemas/FieldInfo"}}}},"sort":{"type":"object","required":["values","default","rules","availability"],"properties":{"values":{"type":"array","items":{"type":"string"}},"default":{"type":"string"},"rules":{"type":"string"},"availability":{"type":"object","required":["url","searchesWithPosts","searchesWithCommentsNoPosts","searchesOther"],"properties":{"url":{"type":"array","items":{"type":"string"}},"searchesWithPosts":{"type":"array","items":{"type":"string"}},"searchesWithCommentsNoPosts":{"type":"array","items":{"type":"string"}},"searchesOther":{"type":"array","items":{"type":"string"}}}}}},"time":{"type":"object","required":["values","default","rules"],"properties":{"values":{"type":"array","items":{"type":"string"}},"default":{"type":"string"},"rules":{"type":"string"}}},"formats":{"type":"object","required":["values","default"],"properties":{"values":{"type":"array","items":{"type":"string"}},"default":{"type":"string"}}},"maxItems":{"type":"object","required":["min","max","default"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"},"default":{"type":"integer"}}},"searches":{"type":"object","required":["maxCount","maxLength"],"properties":{"maxCount":{"type":"integer"},"maxLength":{"type":"integer"}}},"url":{"type":"object","required":["allowedHosts"],"properties":{"allowedHosts":{"type":"array","items":{"type":"string"}}}},"includeNsfw":{"type":"object","required":["default"],"properties":{"default":{"type":"boolean"}}}},"description":"Selectable fields per data type and the rules for request options."},"SubscriptionSummary":{"type":"object","required":["status","plan","priceMonthly","currency","renewalDate","endDate","pendingPlanChange"],"properties":{"status":{"type":"string","enum":["active","pending_cancellation","none"]},"plan":{"type":["string","null"],"description":"Basic, Professional, Enterprise or null."},"priceMonthly":{"type":["string","null"],"pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount with two decimals."},"currency":{"type":"string","const":"usd"},"renewalDate":{"type":["string","null"],"format":"date-time","description":"Next automatic renewal; null when the subscription will not renew."},"endDate":{"type":["string","null"],"format":"date-time","description":"End of the current billing period."},"pendingPlanChange":{"anyOf":[{"$ref":"#/components/schemas/PendingPlanChange"},{"type":"null"}]}}},"PendingPlanChange":{"type":"object","required":["plan","effectiveDate"],"properties":{"plan":{"type":"string"},"effectiveDate":{"type":["string","null"],"format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."}},"description":"A downgrade scheduled for the end of the billing period."},"ApiKeySummary":{"type":"object","required":["id","name","scopes","preset"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["scrapes:read","scrapes:write","account:read","account:write","billing:read","billing:write","keys:read","keys:write"]}},"preset":{"type":"string","enum":["read_only","standard","full","custom"]}},"description":"The API key making the request."},"Account":{"type":"object","required":["id","email","firstName","lastName","dateJoined","subscription","apiKey"],"properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"dateJoined":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"subscription":{"$ref":"#/components/schemas/SubscriptionSummary"},"apiKey":{"$ref":"#/components/schemas/ApiKeySummary"}}},"UpdateAccountRequest":{"type":"object","required":[],"properties":{"firstName":{"type":"string","minLength":1,"maxLength":150},"lastName":{"type":["string","null"],"maxLength":150,"description":"null or \"\" clears the last name."}},"additionalProperties":false,"minProperties":1},"CheckoutRequest":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","description":"Plan id or name, case-insensitive: basic, professional, enterprise.","examples":["professional"]}},"additionalProperties":false},"CheckoutSession":{"type":"object","required":["checkoutUrl","plan"],"properties":{"checkoutUrl":{"type":"string","format":"uri","description":"Stripe Checkout page. A human must open it in a browser to pay."},"plan":{"type":"string"}}},"ChangePlanRequest":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","description":"Plan id or name, case-insensitive: basic, professional, enterprise.","examples":["professional"]},"dryRun":{"type":"boolean","default":false,"description":"true = only preview the change (no charge, nothing saved)."}},"additionalProperties":false},"PlanChange":{"type":"object","required":["currentPlan","newPlan","direction","effective","effectiveDate","priceDifference","currency","message","dryRun"],"properties":{"currentPlan":{"type":"string"},"newPlan":{"type":"string"},"direction":{"type":"string","enum":["upgrade","downgrade"]},"effective":{"type":"string","enum":["immediate","next_period"]},"effectiveDate":{"type":["string","null"],"format":"date-time","description":"null for immediate upgrades."},"priceDifference":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount with two decimals."},"currency":{"type":"string","const":"usd"},"message":{"type":"string"},"dryRun":{"type":"boolean"},"subscription":{"$ref":"#/components/schemas/SubscriptionSummary","description":"Updated subscription (only when dryRun is false)."}}},"CancelSubscriptionRequest":{"type":"object","required":[],"properties":{"dryRun":{"type":"boolean","default":false,"description":"true = only preview the cancellation."}},"additionalProperties":false},"SubscriptionCancellation":{"type":"object","required":["currentPlan","effectiveDate","message","dryRun"],"properties":{"currentPlan":{"type":["string","null"]},"effectiveDate":{"type":["string","null"],"format":"date-time","description":"When access ends (end of the period)."},"message":{"type":"string"},"dryRun":{"type":"boolean"},"subscription":{"$ref":"#/components/schemas/SubscriptionSummary","description":"Updated subscription (only when dryRun is false)."}}},"Transaction":{"type":"object","required":["transactionNumber","date","paymentMethod","amount","currency","plan"],"properties":{"transactionNumber":{"type":"string"},"date":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"paymentMethod":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","description":"Decimal amount with two decimals."},"currency":{"type":"string","const":"usd"},"plan":{"type":["string","null"]}}},"TransactionList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/PagePagination"}},"description":"Payments, newest first."},"Usage":{"type":"object","required":["totalRuns","successfulRuns","failedRuns","totalComputeTimeUsed","totalItemsScraped","totalItemsRequested","successRate","averageRunTime","topDataTypes","recentActivity","monthlyUsage","plan"],"properties":{"totalRuns":{"type":"integer"},"successfulRuns":{"type":"integer"},"failedRuns":{"type":"integer","description":"Failed and canceled runs."},"totalComputeTimeUsed":{"type":"number","description":"Hours, all time."},"totalItemsScraped":{"type":"integer"},"totalItemsRequested":{"type":"integer"},"successRate":{"type":"number","description":"Items scraped / items requested, in percent."},"averageRunTime":{"type":"number","description":"Seconds."},"topDataTypes":{"type":"array","items":{"type":"object","required":["type","count","percentage"],"properties":{"type":{"type":"string","enum":["Posts","Comments","Users","Subreddits"]},"count":{"type":"integer"},"percentage":{"type":"number"}}},"description":"Share of each data type over the last 50 completed scrapes."},"recentActivity":{"type":"array","items":{"type":"object","required":["date","runs","items","status"],"properties":{"date":{"type":"string","format":"date"},"runs":{"type":"integer"},"items":{"type":"integer"},"status":{"type":"string","enum":["success","mixed","failed"]}}},"description":"Up to 5 most recent days with scrapes in the last 7 days."},"monthlyUsage":{"type":"object","required":["currentMonth"],"properties":{"currentMonth":{"type":"number","description":"Compute hours this month."}}},"plan":{"type":"object","required":["name","computeHoursIncluded","computeHoursUsed","computeHoursRemaining","periodStart","periodEnd","concurrentScrapeLimit"],"properties":{"name":{"type":["string","null"]},"computeHoursIncluded":{"type":"integer"},"computeHoursUsed":{"type":"number","description":"Compute hours of scrapes started in the current billing period: finished runs (except failures in under a minute) plus the time so far of running ones."},"computeHoursRemaining":{"type":"number","description":"New scrapes are refused with compute_limit_reached at 0."},"periodStart":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"periodEnd":{"type":"string","format":"date-time","description":"When the allowance renews (ISO-8601 UTC)."},"concurrentScrapeLimit":{"type":"integer","description":"Scrapes the plan may run at once."}},"description":"The compute-hour allowance exactly as enforced when a scrape starts."}},"description":"Same numbers as the dashboard overview, plus the plan compute-hour budget."},"ScrapeRequestSummary":{"type":"object","required":["searches","url","dataTypes","sort","time","includeNsfw","maxItems","format"],"properties":{"searches":{"type":["array","null"],"items":{"type":"string"}},"url":{"type":["string","null"]},"dataTypes":{"type":"object","required":[],"properties":{"posts":{"oneOf":[{"const":true,"description":"Every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["title","content","url","subreddit","username","numComments","upvotes","media","flair","upvoteRatio","mediaType","nsfw"]},"description":"A subset of field keys (see GET /v1/fields)."}]},"comments":{"oneOf":[{"const":true,"description":"Every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["username","communityName","body","createdAt","upvotes","numberOfreplies","url"]},"description":"A subset of field keys (see GET /v1/fields)."}]},"subreddits":{"oneOf":[{"const":true,"description":"Every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["name","createdAt","description","members","moderators","url","rules","title","headerImg"]},"description":"A subset of field keys (see GET /v1/fields)."}]},"users":{"oneOf":[{"const":true,"description":"Every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["username","postKarma","commentKarma","avatarUrl","isModerator","description","createdAt","url","nsfw"]},"description":"A subset of field keys (see GET /v1/fields)."}]}},"description":"Selected data types: true (all fields) or the selected field keys."},"sort":{"type":"string"},"time":{"type":"string"},"includeNsfw":{"type":"boolean"},"maxItems":{"type":["integer","null"]},"format":{"type":["string","null"],"description":"Preferred export format saved for the dashboard."}},"description":"The scrape request (rebuilt for scrapes started in the dashboard too)."},"Scrape":{"type":"object","required":["id","runId","status","source","createdAt","completedAt","computeSeconds","itemCount","itemLimit","accuracy","request","links"],"properties":{"id":{"type":"integer"},"runId":{"type":["string","null"],"description":"Apify run id (also accepted as {id})."},"status":{"type":"string","enum":["running","completed","failed","canceled","unknown"]},"source":{"type":"string","enum":["dashboard","api","mcp"]},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"completedAt":{"type":["string","null"],"format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"computeSeconds":{"type":["number","null"],"description":"null while running."},"itemCount":{"type":"integer","description":"Items returned by the scraper."},"itemLimit":{"type":"integer"},"accuracy":{"type":["number","null"],"description":"Percentage; null unless completed."},"request":{"$ref":"#/components/schemas/ScrapeRequestSummary"},"links":{"type":"object","required":["self","results"],"properties":{"self":{"type":"string"},"results":{"type":"string"}}}}},"ScrapeList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Scrape"}},"pagination":{"$ref":"#/components/schemas/PagePagination"}},"description":"Scrapes, newest first (results not included)."},"CreateScrapeRequest":{"type":"object","required":["dataTypes"],"properties":{"searches":{"type":"array","minItems":1,"maxItems":9,"items":{"type":"string","minLength":1,"maxLength":200},"description":"Keyword searches. Provide searches or url, not both."},"url":{"type":"string","format":"uri","maxLength":2048,"description":"http(s) URL on reddit.com, *.reddit.com or redd.it. Provide searches or url, not both."},"dataTypes":{"type":"object","required":[],"properties":{"posts":{"oneOf":[{"type":"boolean","description":"true = every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["title","content","url","subreddit","username","numComments","upvotes","media","flair","upvoteRatio","mediaType","nsfw"]},"description":"A subset of field keys (see GET /v1/fields)."},{"type":"null"}]},"comments":{"oneOf":[{"type":"boolean","description":"true = every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["username","communityName","body","createdAt","upvotes","numberOfreplies","url"]},"description":"A subset of field keys (see GET /v1/fields)."},{"type":"null"}]},"subreddits":{"oneOf":[{"type":"boolean","description":"true = every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["name","createdAt","description","members","moderators","url","rules","title","headerImg"]},"description":"A subset of field keys (see GET /v1/fields)."},{"type":"null"}]},"users":{"oneOf":[{"type":"boolean","description":"true = every field of this data type."},{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["username","postKarma","commentKarma","avatarUrl","isModerator","description","createdAt","url","nsfw"]},"description":"A subset of field keys (see GET /v1/fields)."},{"type":"null"}]}},"description":"Data types to collect. At least one must be true or a non-empty list of field keys.","additionalProperties":false,"minProperties":1},"sort":{"type":"string","enum":["none","hot","top","new","relevance"],"default":"none","description":"Sorting only applies to keyword searches (not url). With posts selected every sort is allowed; with comments but no posts, \"hot\" is not available; otherwise only \"none\" is allowed."},"time":{"type":"string","enum":["all","hour","day","week","month","year"],"default":"all","description":"The time filter only applies to keyword searches that include posts; otherwise it must be \"all\"."},"includeNsfw":{"type":"boolean","default":true},"maxItems":{"type":"integer","minimum":1,"maximum":10000,"default":50},"format":{"type":"string","enum":["json","csv","xml","excel"],"default":"json","description":"Preferred export format saved with the scrape (dashboard downloads). Use the results endpoint format parameter to choose a download format."}},"additionalProperties":false,"oneOf":[{"required":["searches"]},{"required":["url"]}]},"ResultRow":{"type":"object","required":["type"],"additionalProperties":true,"properties":{"type":{"type":"string","description":"post, submission, comment, subreddit, community or user."},"id":{"description":"Reddit id of the item."},"url":{"description":"Permalink of the item."}},"description":"One scraped item with the selected fields (keys from GET /v1/fields)."},"ScrapeResultsPage":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResultRow"}},"pagination":{"$ref":"#/components/schemas/OffsetPagination"}}},"ApiKey":{"type":"object","required":["id","name","scopes","preset","createdAt","lastUsedAt","revoked","revokedAt","current"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["scrapes:read","scrapes:write","account:read","account:write","billing:read","billing:write","keys:read","keys:write"]}},"preset":{"type":"string","enum":["read_only","standard","full","custom"],"description":"Preset matching the scopes exactly, else \"custom\"."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"revoked":{"type":"boolean"},"revokedAt":{"type":["string","null"],"format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"current":{"type":"boolean","description":"True for the key making this request."}},"description":"An API key (the secret is never returned again)."},"ApiKeyList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"pagination":{"$ref":"#/components/schemas/PagePagination"}},"description":"API keys (active and revoked), newest first."},"CreateApiKeyRequest":{"type":"object","required":[],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"default":"API Key"},"preset":{"type":"string","enum":["read_only","standard","full"],"default":"standard"},"scopes":{"type":"array","minItems":1,"items":{"type":"string","enum":["scrapes:read","scrapes:write","account:read","account:write","billing:read","billing:write","keys:read","keys:write"]},"description":"Explicit scopes (instead of preset)."}},"description":"Send preset or scopes, not both. The new key cannot have scopes the calling key lacks.","additionalProperties":false},"CreatedApiKey":{"type":"object","required":["id","name","scopes","preset","createdAt","lastUsedAt","revoked","revokedAt","current","secret","message"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["scrapes:read","scrapes:write","account:read","account:write","billing:read","billing:write","keys:read","keys:write"]}},"preset":{"type":"string","enum":["read_only","standard","full","custom"],"description":"Preset matching the scopes exactly, else \"custom\"."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"lastUsedAt":{"type":["string","null"],"format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"revoked":{"type":"boolean"},"revokedAt":{"type":["string","null"],"format":"date-time","description":"ISO-8601 UTC timestamp (Z suffix)."},"current":{"type":"boolean","description":"True for the key making this request."},"secret":{"type":"string","description":"The API key. Returned only once; store it securely."},"message":{"type":"string"}}},"SupportRequest":{"type":"object","required":["message"],"properties":{"subject":{"type":"string","maxLength":200},"message":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false},"SupportAccepted":{"type":"object","required":["status"],"properties":{"status":{"type":"string","const":"sent"}}},"OpenAPIDocument":{"type":"object","additionalProperties":true,"description":"This document."}},"parameters":{"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"ScrapeId":{"name":"id","in":"path","required":true,"description":"Scrape id (integer) or Apify run id.","schema":{"type":"string"}},"KeyId":{"name":"id","in":"path","required":true,"description":"API key id.","schema":{"type":"integer"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional client-chosen key. Repeating a request with the same key returns the scrape created by the first request (200 + Idempotent-Replayed: true) instead of starting another one.","schema":{"type":"string","maxLength":255}}},"headers":{"ApiVersion":{"description":"API version that served the request.","schema":{"type":"string","const":"1"}},"WWWAuthenticate":{"description":"Authentication challenge.","schema":{"type":"string","examples":["Bearer realm=\"RedScraper API\""]}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"PollRetryAfter":{"description":"Present when the scrape is still running and the requested wait was skipped because the server is busy: seconds to wait before polling again.","schema":{"type":"integer"}},"IdempotentReplayed":{"description":"Present (true) when the response replays an earlier request.","schema":{"type":"string","const":"true"}},"Location":{"description":"Path of the created scrape.","schema":{"type":"string"}},"ContentDisposition":{"description":"attachment; filename=\"redscraper-<id>.<ext>\"","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"Invalid request (validation_error with details per field, or invalid_json).","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"validation_error","message":"The request is invalid."}}}}},"Unauthorized":{"description":"Missing, invalid or revoked API key, or a dashboard session token was sent.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthenticated","message":"Invalid or revoked API key."}}}}},"Forbidden":{"description":"The API key lacks the required scope (details.requiredScope).","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: scrapes:write"}}}}},"PaymentRequired":{"description":"An active subscription is required.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"subscription_required","message":"An active subscription is required. Subscribe to a plan first."}}}}},"ScrapePaymentRequired":{"description":"subscription_required (no active subscription) or compute_limit_reached (the plan's compute hours for this billing period are used up; details.usage has the numbers and periodEnd, when they renew).","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"compute_limit_reached","message":"You have used all the compute hours included in your plan for this billing period (10 of 10 hours). They renew on December 1, 2026. Upgrade your plan to keep scraping before then."}}}}},"ScrapeLimited":{"description":"rate_limited (too many requests for this API key; see Retry-After) or concurrent_limit_reached (the plan's number of scrapes running at once is reached; details.running and details.limit). Wait for a scrape to finish before starting another.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"concurrent_limit_reached","message":"You already have 2 scrapes running, the most your plan allows at once (2). Wait for one to finish, then try again."}}}}},"NotFound":{"description":"Not found (or not owned by this account).","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Scrape not found."}}}}},"Conflict":{"description":"The request conflicts with the current state (details explain why).","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"Results are only available for completed scrapes (status: running)."}}}}},"UnsupportedMediaType":{"description":"The body must be sent as application/json.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unsupported_media_type","message":"Unsupported media type \"text/plain\" in request."}}}}},"PayloadTooLarge":{"description":"The request body is larger than the server accepts.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"payload_too_large","message":"Request body is too large (the limit is 2621440 bytes)."}}}}},"RateLimited":{"description":"Too many requests for this API key.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many requests. Slow down and retry later."}}}}},"UpstreamError":{"description":"The scraping or payment provider failed; retry shortly.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"upstream_error","message":"Could not reach the scraping provider. Please try again shortly."}}}}},"InternalError":{"description":"Unexpected server error.","headers":{"X-RedScraper-Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred. Please try again later."}}}}}}}}