{ "openapi": "3.0.3", "info": { "title": "CrawlBrulee API", "version": "1.0.0", "description": "Web scraping API for extracting structured data from websites." }, "components": { "securitySchemes": { "apiToken": { "type": "http", "scheme": "bearer" } }, "schemas": {} }, "paths": { "/api/scrape": { "post": { "tags": [ "Scraping" ], "description": "Scrape a URL synchronously and return the extracted content. The returned url comes back in normalized form. Known tracking parameters are removed. /map applies the same normalization to every link it returns.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to scrape. Known tracking parameters are removed before the page is fetched, so they are neither sent to the target site nor part of the cache key. Every other query parameter is kept verbatim and is part of the cache key." }, "extract": { "description": "Which content formats to extract. Defaults to metadata + cleaned_html.", "default": {}, "type": "object", "properties": { "metadata": { "default": true, "description": "Extract page metadata (title, description, OG tags, etc.)", "type": "boolean" }, "cleaned_html": { "default": true, "description": "Return the page HTML with scripts, styles and cleanup applied", "type": "boolean" }, "markdown": { "default": false, "description": "Extract page content as clean Markdown", "type": "boolean" }, "raw_html": { "default": false, "description": "Return the raw, unprocessed HTML", "type": "boolean" }, "links": { "default": false, "description": "Extract all links found on the page", "type": "boolean" }, "images": { "default": false, "description": "Extract all inline images found on the page", "type": "boolean" }, "screenshot": { "description": "Capture a screenshot of the page", "type": "object", "properties": { "type": { "type": "string", "enum": [ "viewport", "full_page" ], "description": "Screenshot capture mode" }, "viewport": { "description": "Custom viewport dimensions; uses device_mode defaults if omitted", "type": "object", "properties": { "width": { "type": "integer", "minimum": 16, "maximum": 10000, "description": "Viewport width in pixels (16–10000)" }, "height": { "type": "integer", "minimum": 16, "maximum": 10000, "description": "Viewport height in pixels (16–10000)" }, "device_scale_factor": { "description": "Device pixel ratio (1–3, fractional allowed; e.g. 2 for Retina). Defaults to 1.", "type": "number", "minimum": 1, "maximum": 3 } }, "required": [ "width", "height" ], "additionalProperties": false }, "device_mode": { "default": "desktop", "description": "Emulate desktop or mobile device viewport", "type": "string", "enum": [ "desktop", "mobile" ] }, "actions_before": { "default": [], "description": "Actions to perform before taking the screenshot (wait, scroll)", "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wait" ], "description": "Wait for a duration before capturing" }, "ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Milliseconds to wait" } }, "required": [ "type", "ms" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll" ], "description": "Scroll the page before capturing" }, "pixels": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Pixels to scroll (positive = down, negative = up)" } }, "required": [ "type", "pixels" ] } ] } }, "actions_after": { "default": [], "description": "Actions to perform after taking the screenshot (e.g. slice into tiles)", "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "slice" ], "description": "Slice the screenshot into horizontal tiles" }, "height": { "type": "integer", "minimum": 500, "maximum": 9007199254740991, "description": "Height of each tile in pixels (minimum 500)" } }, "required": [ "type", "height" ] } } }, "required": [ "type" ], "additionalProperties": false } }, "additionalProperties": false }, "cache": { "description": "Cache settings for this request", "type": "object", "properties": { "max_age": { "default": 172800, "description": "Maximum cache age in seconds, or an ISO 8601 datetime cutoff", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": false }, "require_js": { "default": false, "description": "Use a headless browser to render JavaScript before scraping", "type": "boolean" }, "cleanup": { "default": {}, "type": "object", "properties": { "ads_and_popups": { "default": true, "description": "Remove ads, cookie banners, consent dialogs and chat widgets. Defaults to true. Also affects the screenshot. Set it to false to capture the page as-is, and to get past a site that refuses to serve visitors it thinks are blocking ads.", "type": "boolean" }, "exclude_selectors": { "description": "CSS selectors whose elements are removed before anything is captured. Affects the extracted content and the screenshot, never raw_html. Use it for a banner or widget that ads_and_popups does not recognise.", "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 500 } } }, "additionalProperties": false, "description": "What is removed from the page before any output is built. Applies to markdown, cleaned_html, links and images on every engine, and to the screenshot where noted. Never applies to raw_html, which is always the page before we removed anything." }, "proxy": { "default": "auto", "description": "Proxy tier to use for fetching", "type": "string", "enum": [ "basic", "advanced", "auto" ] }, "location": { "type": "object", "properties": { "locale": { "description": "BCP-47 locale (2-35 chars, e.g. 'en-US', 'de-DE', 'pt-BR') driving Accept-Language and navigator.language", "type": "string", "minLength": 2, "maxLength": 35 }, "country": { "description": "ISO 3166-1 alpha-2 (e.g. 'us', 'de', 'br'; case-insensitive) driving the emulated browser timezone and proxy exit country. Also accepts 'eu' (random EU member state) or 'europe' (random European state incl. UK and non-EU).", "type": "string", "pattern": "^([a-zA-Z]{2}|[eE][uU][rR][oO][pP][eE])$" } }, "additionalProperties": false, "description": "Optional locale + country emulation for the scrape" } }, "required": [ "url" ], "additionalProperties": false } } }, "required": true }, "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL that was actually scraped, after any redirects, in normalized form — the base that links, images, and internal labels are computed against" }, "requested_url": { "type": "string", "description": "The URL you requested, echoed verbatim — before any redirects" }, "content_type": { "description": "Content-Type header returned by the server", "type": "string" }, "unsupported_fields": { "description": "Extract fields that were requested but are not supported for this content type", "type": "array", "items": { "type": "string" } }, "markdown": { "description": "Page content converted to clean Markdown", "type": "string" }, "cleaned_html": { "description": "Cleaned HTML of the main page content", "type": "string" }, "raw_html": { "description": "Raw, unprocessed HTML of the page", "type": "string" }, "images": { "description": "Inline images found on the page", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Absolute URL of the image" }, "alt": { "nullable": true, "description": "Alt text of the image, or null if not set", "type": "string" } }, "required": [ "url", "alt" ], "additionalProperties": false } }, "links": { "description": "Links found on the page", "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Anchor text of the link" }, "href": { "type": "string", "description": "The link URL as written on the page, resolved to an absolute URL. Verbatim otherwise: query string, fragment, and duplicates are preserved — cleaning is up to the consumer." }, "internal": { "type": "boolean", "description": "Whether the link points to the same domain (www and the bare domain are equivalent; other subdomains are external)" } }, "required": [ "text", "href", "internal" ], "additionalProperties": false } }, "screenshot": { "description": "Screenshot of the page, if requested", "type": "object", "properties": { "url": { "type": "string", "description": "URL to download the full screenshot image" }, "type": { "type": "string", "enum": [ "viewport", "full_page" ], "description": "Screenshot capture mode that was used" }, "properties": { "type": "object", "properties": { "file_name": { "type": "string", "description": "File name of the screenshot image" }, "mime": { "type": "string", "description": "MIME type of the screenshot (image/webp, or image/jpeg for very tall captures)" }, "width": { "type": "number", "description": "Image width in pixels" }, "height": { "type": "number", "description": "Image height in pixels" }, "viewport": { "type": "object", "properties": { "width": { "type": "number", "description": "Viewport width in pixels" }, "height": { "type": "number", "description": "Viewport height in pixels" }, "device_scale_factor": { "type": "number", "description": "Device pixel ratio used for the capture" } }, "required": [ "width", "height", "device_scale_factor" ], "additionalProperties": false, "description": "Viewport dimensions used during capture" } }, "required": [ "file_name", "mime", "width", "height", "viewport" ], "additionalProperties": false, "description": "Image properties for the full screenshot" }, "slices": { "description": "Individual tile slices (present when slice action_after was requested)", "type": "array", "items": { "type": "object", "properties": { "row_nr": { "type": "number", "description": "Row index of this slice (0-based)" }, "url": { "type": "string", "description": "URL to download this slice image" }, "type": { "type": "string", "enum": [ "slice" ], "description": "Slice type identifier" }, "properties": { "type": "object", "properties": { "file_name": { "type": "string", "description": "File name of the screenshot image" }, "mime": { "type": "string", "description": "MIME type of the screenshot (image/webp, or image/jpeg for very tall captures)" }, "width": { "type": "number", "description": "Image width in pixels" }, "height": { "type": "number", "description": "Image height in pixels" }, "viewport": { "type": "object", "properties": { "width": { "type": "number", "description": "Viewport width in pixels" }, "height": { "type": "number", "description": "Viewport height in pixels" }, "device_scale_factor": { "type": "number", "description": "Device pixel ratio used for the capture" } }, "required": [ "width", "height", "device_scale_factor" ], "additionalProperties": false, "description": "Viewport dimensions used during capture" } }, "required": [ "file_name", "mime", "width", "height", "viewport" ], "additionalProperties": false, "description": "Image properties for this slice" } }, "required": [ "row_nr", "url", "type", "properties" ], "additionalProperties": false } } }, "required": [ "url", "type", "properties" ], "additionalProperties": false }, "metadata": { "description": "Extracted page/SEO metadata (title, OG tags, etc.)", "type": "object", "properties": { "title": { "description": "Page title from the tag", "type": "string" }, "description": { "description": "Meta description", "type": "string" }, "keywords": { "description": "Meta keywords", "type": "array", "items": { "type": "string" } }, "canonical": { "description": "Canonical URL specified by the page", "type": "string" }, "og_url": { "description": "Open Graph URL", "type": "string" }, "og_title": { "description": "Open Graph title", "type": "string" }, "og_description": { "description": "Open Graph description", "type": "string" }, "og_type": { "description": "Open Graph type (e.g. article, website)", "type": "string" }, "og_site_name": { "description": "Open Graph site name", "type": "string" }, "og_locale": { "description": "Open Graph locale (e.g. en_US)", "type": "string" }, "og_locale_alternate": { "description": "Alternate Open Graph locales", "type": "array", "items": { "type": "string" } }, "og_image": { "description": "Open Graph image URL", "type": "string" }, "author": { "description": "Article author", "type": "string" }, "date_modified": { "description": "Article last-modified date", "type": "string" }, "date_published": { "description": "Article publication date", "type": "string" }, "twitter_site": { "description": "Twitter @username for the site", "type": "string" }, "twitter_card": { "description": "Twitter card type (e.g. summary_large_image)", "type": "string" }, "twitter_description": { "description": "Twitter card description", "type": "string" }, "twitter_title": { "description": "Twitter card title", "type": "string" }, "twitter_image": { "description": "Twitter card image URL", "type": "string" }, "robots": { "description": "Robots meta directive (e.g. noindex, nofollow)", "type": "string" }, "favicon_url": { "description": "Resolved favicon URL for the page (best-effort, from <head> icon hints + manifest)", "nullable": true, "type": "string" } }, "additionalProperties": false }, "response_meta": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Credits actually charged for this request. Always equals the engine base × the proxy multiplier, plus screenshot_slices. A cache hit has engine \"cache\" (base 0), so it costs only the parts we still had to compute — a newly produced screenshot-slice variant — and is otherwise free." }, "engine": { "type": "string", "enum": [ "http", "browser", "screenshot", "cache" ], "description": "The engine base the request was billed at — \"http\" (1 credit), \"browser\" (3), \"screenshot\" (5), or \"cache\" (0, the result was served from cache) — before the proxy multiplier. Reflects what was delivered, never what was requested." }, "proxy": { "type": "string", "enum": [ "basic", "advanced" ], "description": "The proxy tier that actually resolved the request — the resolved tier, never \"auto\". \"advanced\" multiplies the engine base by 5." }, "screenshot_slices": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Whether this request was billed the screenshot-split add-on: 1 when the screenshot was split on this request (a flat +1 credit outside the proxy multiplier, regardless of how many slices the split produced), else 0 — including a cache hit that reused an already-existing slice variant." } }, "required": [ "credits", "engine", "proxy", "screenshot_slices" ], "additionalProperties": false } }, "required": [ "usage" ], "additionalProperties": false, "description": "Operation metadata for this response (usage/billing)." }, "warnings": { "description": "Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded. `screenshot_unavailable` means a screenshot was requested but, after the browser priority window, the http engine returned the page without one. Stable string codes — clients can switch on them. Warnings are stored with the result and filtered to the fields your request asked for. `metadata_truncated` is retired: metadata no longer has a size budget of its own, so new scrapes never emit it, though it may still appear on results stored before that change.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "requested_url", "response_meta" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "408": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "415": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "499": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } } } } }, "/api/map": { "post": { "tags": [ "Scraping" ], "description": "Build or return a cached site link map using sitemap discovery plus homepage link discovery. By default the map holds up to 5000 URLs (max_urls, maximum 100000) and returns up to 5000 per page (limit, maximum 10000). Sitemap discovery stops as soon as max_urls URLs have been found, so raising it is a bigger crawl and lowering it is a faster one. When discovery stops early, response_meta.truncation.discovery_cap_reason names the limit that stopped it. Returned URLs come back in normalized form, the same normalization /scrape applies to its returned url. Known tracking parameters are removed. Links are ordered so the most useful ones land on page 1.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The website URL to map. Mapping always targets the site root, so the path, query string and fragment are dropped; known tracking parameters are removed before the page is fetched." }, "proxy": { "default": "auto", "description": "Proxy tier to use for fetching", "type": "string", "enum": [ "basic", "advanced", "auto" ] }, "sitemap_only": { "default": false, "description": "Only use sitemap.xml — skip homepage link extraction", "type": "boolean" }, "types": { "description": "Filter which link types to include", "type": "object", "properties": { "internal": { "default": true, "description": "Include internal links (same domain; www and the bare domain are equivalent)", "type": "boolean" }, "internal_subdomains": { "default": true, "description": "Include links to subdomains of the target domain (other than www)", "type": "boolean" }, "external": { "default": true, "description": "Include external links (different domains)", "type": "boolean" } } }, "cache": { "description": "Cache settings for this request", "type": "object", "properties": { "max_age": { "default": 604800, "description": "Maximum cache age in seconds, or an ISO 8601 datetime cutoff", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string", "format": "date-time" } ] } } }, "max_urls": { "default": 5000, "description": "Maximum number of URLs to discover and store in the map. Default 5000, maximum 100000. Sitemap discovery stops as soon as this many URLs have been found, so a smaller value is a faster and lighter crawl, not just a smaller answer.", "type": "integer", "exclusiveMinimum": true, "maximum": 100000 }, "page": { "default": 1, "description": "Page number for paginated results", "type": "integer", "exclusiveMinimum": true, "maximum": 9007199254740991 }, "limit": { "default": 5000, "description": "Number of URLs to return per page. Default 5000, maximum 10000.", "type": "integer", "exclusiveMinimum": true, "maximum": 10000 }, "location": { "type": "object", "properties": { "country": { "description": "ISO 3166-1 alpha-2 (e.g. 'us', 'de', 'br'; case-insensitive) hint for proxy egress country. Also accepts 'eu' (random EU member state) or 'europe' (random European state incl. UK and non-EU).", "type": "string", "pattern": "^([a-zA-Z]{2}|[eE][uU][rR][oO][pP][eE])$" } }, "additionalProperties": false, "description": "Optional country emulation for the map" } }, "required": [ "url" ] } } }, "required": true }, "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The discovered URL" } }, "required": [ "url" ], "additionalProperties": false }, "description": "List of discovered URLs for the current page" }, "response_meta": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Credits actually charged for this map request. A fresh map costs the http engine base multiplied by the resolved proxy tier; a cache hit is free." }, "engine": { "type": "string", "enum": [ "http", "cache" ], "description": "The map billing engine: \"http\" for fresh discovery or \"cache\" when the result was served from cache." }, "proxy": { "type": "string", "enum": [ "basic", "advanced" ], "description": "The proxy tier that actually resolved the request — the resolved tier, never \"auto\". \"advanced\" multiplies the http engine base by 5." } }, "required": [ "credits", "engine", "proxy" ], "additionalProperties": false, "description": "Usage/billing for this map request" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "exclusiveMinimum": true, "maximum": 9007199254740991, "description": "Current page number" }, "limit": { "type": "integer", "exclusiveMinimum": true, "maximum": 9007199254740991, "description": "Number of items per page" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total number of URLs in the map" }, "total_pages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total number of pages available" }, "has_more": { "type": "boolean", "description": "Whether more pages are available" } }, "required": [ "page", "limit", "total", "total_pages", "has_more" ], "additionalProperties": false, "description": "Pagination details for the result set" }, "truncation": { "type": "object", "properties": { "storage_capped": { "type": "boolean", "description": "Whether the stored map hit the 100000-URL storage cap." }, "response_capped": { "type": "boolean", "description": "Whether more links were eligible than max_urls, so the list was trimmed. Discovery itself stops at max_urls, so this is normally true only when home-page links pushed the total past it. See discovery_cap_reason for a discovery stop." }, "total_before_max_urls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total URLs found before applying the max_urls cap" }, "total_detected_before_storage_cap": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total URLs detected during discovery before the storage cap was applied" }, "discovery_capped": { "type": "boolean", "description": "Whether sitemap discovery stopped before it had read every sitemap file it found. When true, the site has more pages than this map lists." }, "sitemaps_skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many sitemap files were skipped or only partly read during discovery, because a file was too large, could not be fetched, or the discovery limits were reached." }, "discovery_cap_reason": { "nullable": true, "description": "Which limit stopped sitemap discovery first, or null when nothing stopped it. \"max_urls\" means your own max_urls was reached — ask again with a higher one to get more. \"time\" means discovery ran out of its time budget, \"file_budget\" that the site has more sitemap files than one request reads, \"depth\" that its sitemap indexes nest too deeply, and \"file_size\" that a sitemap file was too large to read. \"unread_files\" means a sitemap file the site publishes could not be read at all this time — the request for it failed or was rate limited, or the file was not a readable sitemap. Only \"max_urls\" is a limit you can raise from the request; \"unread_files\" is often temporary, so asking again later can return more.", "type": "string", "enum": [ "max_urls", "time", "file_budget", "depth", "file_size", "unread_files", null ] } }, "required": [ "storage_capped", "response_capped", "total_before_max_urls", "total_detected_before_storage_cap", "discovery_capped", "sitemaps_skipped", "discovery_cap_reason" ], "additionalProperties": false, "description": "Information about whether the results were truncated" } }, "required": [ "usage", "pagination", "truncation" ], "additionalProperties": false, "description": "Response metadata including usage, pagination and truncation info" } }, "required": [ "links", "response_meta" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "408": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "499": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } } } } }, "/api/scrape/async": { "post": { "tags": [ "Scraping" ], "description": "Submit an asynchronous scrape job", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to scrape. Known tracking parameters are removed before the page is fetched, so they are neither sent to the target site nor part of the cache key. Every other query parameter is kept verbatim and is part of the cache key." }, "extract": { "description": "Which content formats to extract. Defaults to metadata + cleaned_html.", "default": {}, "type": "object", "properties": { "metadata": { "default": true, "description": "Extract page metadata (title, description, OG tags, etc.)", "type": "boolean" }, "cleaned_html": { "default": true, "description": "Return the page HTML with scripts, styles and cleanup applied", "type": "boolean" }, "markdown": { "default": false, "description": "Extract page content as clean Markdown", "type": "boolean" }, "raw_html": { "default": false, "description": "Return the raw, unprocessed HTML", "type": "boolean" }, "links": { "default": false, "description": "Extract all links found on the page", "type": "boolean" }, "images": { "default": false, "description": "Extract all inline images found on the page", "type": "boolean" }, "screenshot": { "description": "Capture a screenshot of the page", "type": "object", "properties": { "type": { "type": "string", "enum": [ "viewport", "full_page" ], "description": "Screenshot capture mode" }, "viewport": { "description": "Custom viewport dimensions; uses device_mode defaults if omitted", "type": "object", "properties": { "width": { "type": "integer", "minimum": 16, "maximum": 10000, "description": "Viewport width in pixels (16–10000)" }, "height": { "type": "integer", "minimum": 16, "maximum": 10000, "description": "Viewport height in pixels (16–10000)" }, "device_scale_factor": { "description": "Device pixel ratio (1–3, fractional allowed; e.g. 2 for Retina). Defaults to 1.", "type": "number", "minimum": 1, "maximum": 3 } }, "required": [ "width", "height" ], "additionalProperties": false }, "device_mode": { "default": "desktop", "description": "Emulate desktop or mobile device viewport", "type": "string", "enum": [ "desktop", "mobile" ] }, "actions_before": { "default": [], "description": "Actions to perform before taking the screenshot (wait, scroll)", "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wait" ], "description": "Wait for a duration before capturing" }, "ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Milliseconds to wait" } }, "required": [ "type", "ms" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scroll" ], "description": "Scroll the page before capturing" }, "pixels": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Pixels to scroll (positive = down, negative = up)" } }, "required": [ "type", "pixels" ] } ] } }, "actions_after": { "default": [], "description": "Actions to perform after taking the screenshot (e.g. slice into tiles)", "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "slice" ], "description": "Slice the screenshot into horizontal tiles" }, "height": { "type": "integer", "minimum": 500, "maximum": 9007199254740991, "description": "Height of each tile in pixels (minimum 500)" } }, "required": [ "type", "height" ] } } }, "required": [ "type" ], "additionalProperties": false } }, "additionalProperties": false }, "cache": { "description": "Cache settings for this request", "type": "object", "properties": { "max_age": { "default": 172800, "description": "Maximum cache age in seconds, or an ISO 8601 datetime cutoff", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": false }, "require_js": { "default": false, "description": "Use a headless browser to render JavaScript before scraping", "type": "boolean" }, "cleanup": { "default": {}, "type": "object", "properties": { "ads_and_popups": { "default": true, "description": "Remove ads, cookie banners, consent dialogs and chat widgets. Defaults to true. Also affects the screenshot. Set it to false to capture the page as-is, and to get past a site that refuses to serve visitors it thinks are blocking ads.", "type": "boolean" }, "exclude_selectors": { "description": "CSS selectors whose elements are removed before anything is captured. Affects the extracted content and the screenshot, never raw_html. Use it for a banner or widget that ads_and_popups does not recognise.", "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 500 } } }, "additionalProperties": false, "description": "What is removed from the page before any output is built. Applies to markdown, cleaned_html, links and images on every engine, and to the screenshot where noted. Never applies to raw_html, which is always the page before we removed anything." }, "proxy": { "default": "auto", "description": "Proxy tier to use for fetching", "type": "string", "enum": [ "basic", "advanced", "auto" ] }, "location": { "type": "object", "properties": { "locale": { "description": "BCP-47 locale (2-35 chars, e.g. 'en-US', 'de-DE', 'pt-BR') driving Accept-Language and navigator.language", "type": "string", "minLength": 2, "maxLength": 35 }, "country": { "description": "ISO 3166-1 alpha-2 (e.g. 'us', 'de', 'br'; case-insensitive) driving the emulated browser timezone and proxy exit country. Also accepts 'eu' (random EU member state) or 'europe' (random European state incl. UK and non-EU).", "type": "string", "pattern": "^([a-zA-Z]{2}|[eE][uU][rR][oO][pP][eE])$" } }, "additionalProperties": false, "description": "Optional locale + country emulation for the scrape" }, "webhook": { "description": "Optional completion webhook for this job. Configure your signing secret in the dashboard.", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Endpoint to receive a single signed POST when this job reaches a terminal state. HTTPS is required in production. The POST body carries the job outcome, your `metadata` echo, and usage under `response_meta`, shaped as: { event_id, timestamp, event: \"scrape.complete\", data: { job_id, status: \"success\"|\"failed\"|\"cancelled\", url, completed_at, error?, metadata?, response_meta? } }. Deliveries are signed with your organization webhook secret on the X-Cwbl-Signature header: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">. To verify: recompute the HMAC over \"<t>.<raw body bytes>\", constant-time-compare with v1, and reject when |now - t| exceeds 300 seconds. During a signing-secret rotation grace window the previous key also signs the X-Cwbl-Signature-Rotated header — accept either while you migrate. Failed deliveries are retried after 1m, 5m, and 30m (4 attempts total)." }, "metadata": { "description": "Opaque metadata object echoed verbatim in the webhook payload `data.metadata` (max 2048 bytes serialized). Use it to route deliveries without keeping your own job_id mapping.", "type": "object", "additionalProperties": {} } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "url" ], "additionalProperties": false } } }, "required": true }, "security": [ { "apiToken": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the submitted async scrape job" } }, "required": [ "job_id" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "408": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "499": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } } } } }, "/api/scrape/status/{job_id}": { "get": { "tags": [ "Scraping" ], "description": "Check the status of an async scrape job", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "job_id", "required": true, "description": "The job ID returned when the async scrape was submitted" } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The job ID" }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ], "description": "Current state of the job" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the job was created" }, "error": { "description": "Error message if the job failed", "type": "string" }, "response_meta": { "description": "Operation metadata (usage/billing); present once the job is done.", "type": "object", "properties": { "usage": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Credits actually charged for this request. Always equals the engine base × the proxy multiplier, plus screenshot_slices. A cache hit has engine \"cache\" (base 0), so it costs only the parts we still had to compute — a newly produced screenshot-slice variant — and is otherwise free." }, "engine": { "type": "string", "enum": [ "http", "browser", "screenshot", "cache" ], "description": "The engine base the request was billed at — \"http\" (1 credit), \"browser\" (3), \"screenshot\" (5), or \"cache\" (0, the result was served from cache) — before the proxy multiplier. Reflects what was delivered, never what was requested." }, "proxy": { "type": "string", "enum": [ "basic", "advanced" ], "description": "The proxy tier that actually resolved the request — the resolved tier, never \"auto\". \"advanced\" multiplies the engine base by 5." }, "screenshot_slices": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Whether this request was billed the screenshot-split add-on: 1 when the screenshot was split on this request (a flat +1 credit outside the proxy multiplier, regardless of how many slices the split produced), else 0 — including a cache hit that reused an already-existing slice variant." } }, "required": [ "credits", "engine", "proxy", "screenshot_slices" ], "additionalProperties": false } }, "required": [ "usage" ], "additionalProperties": false } }, "required": [ "job_id", "status", "created_at" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "408": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "499": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } } } } }, "/api/scrape/result/{job_id}": { "get": { "tags": [ "Scraping" ], "description": "Retrieve the result of a completed async scrape job", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "job_id", "required": true, "description": "The job ID returned when the async scrape was submitted" } ], "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL that was actually scraped, after any redirects, in normalized form — the base that links, images, and internal labels are computed against" }, "requested_url": { "type": "string", "description": "The URL you requested, echoed verbatim — before any redirects" }, "content_type": { "description": "Content-Type header returned by the server", "type": "string" }, "unsupported_fields": { "description": "Extract fields that were requested but are not supported for this content type", "type": "array", "items": { "type": "string" } }, "markdown": { "description": "Page content converted to clean Markdown", "type": "string" }, "cleaned_html": { "description": "Cleaned HTML of the main page content", "type": "string" }, "raw_html": { "description": "Raw, unprocessed HTML of the page", "type": "string" }, "images": { "description": "Inline images found on the page", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Absolute URL of the image" }, "alt": { "nullable": true, "description": "Alt text of the image, or null if not set", "type": "string" } }, "required": [ "url", "alt" ], "additionalProperties": false } }, "links": { "description": "Links found on the page", "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Anchor text of the link" }, "href": { "type": "string", "description": "The link URL as written on the page, resolved to an absolute URL. Verbatim otherwise: query string, fragment, and duplicates are preserved — cleaning is up to the consumer." }, "internal": { "type": "boolean", "description": "Whether the link points to the same domain (www and the bare domain are equivalent; other subdomains are external)" } }, "required": [ "text", "href", "internal" ], "additionalProperties": false } }, "screenshot": { "description": "Screenshot of the page, if requested", "type": "object", "properties": { "url": { "type": "string", "description": "URL to download the full screenshot image" }, "type": { "type": "string", "enum": [ "viewport", "full_page" ], "description": "Screenshot capture mode that was used" }, "properties": { "type": "object", "properties": { "file_name": { "type": "string", "description": "File name of the screenshot image" }, "mime": { "type": "string", "description": "MIME type of the screenshot (image/webp, or image/jpeg for very tall captures)" }, "width": { "type": "number", "description": "Image width in pixels" }, "height": { "type": "number", "description": "Image height in pixels" }, "viewport": { "type": "object", "properties": { "width": { "type": "number", "description": "Viewport width in pixels" }, "height": { "type": "number", "description": "Viewport height in pixels" }, "device_scale_factor": { "type": "number", "description": "Device pixel ratio used for the capture" } }, "required": [ "width", "height", "device_scale_factor" ], "additionalProperties": false, "description": "Viewport dimensions used during capture" } }, "required": [ "file_name", "mime", "width", "height", "viewport" ], "additionalProperties": false, "description": "Image properties for the full screenshot" }, "slices": { "description": "Individual tile slices (present when slice action_after was requested)", "type": "array", "items": { "type": "object", "properties": { "row_nr": { "type": "number", "description": "Row index of this slice (0-based)" }, "url": { "type": "string", "description": "URL to download this slice image" }, "type": { "type": "string", "enum": [ "slice" ], "description": "Slice type identifier" }, "properties": { "type": "object", "properties": { "file_name": { "type": "string", "description": "File name of the screenshot image" }, "mime": { "type": "string", "description": "MIME type of the screenshot (image/webp, or image/jpeg for very tall captures)" }, "width": { "type": "number", "description": "Image width in pixels" }, "height": { "type": "number", "description": "Image height in pixels" }, "viewport": { "type": "object", "properties": { "width": { "type": "number", "description": "Viewport width in pixels" }, "height": { "type": "number", "description": "Viewport height in pixels" }, "device_scale_factor": { "type": "number", "description": "Device pixel ratio used for the capture" } }, "required": [ "width", "height", "device_scale_factor" ], "additionalProperties": false, "description": "Viewport dimensions used during capture" } }, "required": [ "file_name", "mime", "width", "height", "viewport" ], "additionalProperties": false, "description": "Image properties for this slice" } }, "required": [ "row_nr", "url", "type", "properties" ], "additionalProperties": false } } }, "required": [ "url", "type", "properties" ], "additionalProperties": false }, "metadata": { "description": "Extracted page/SEO metadata (title, OG tags, etc.)", "type": "object", "properties": { "title": { "description": "Page title from the <title> tag", "type": "string" }, "description": { "description": "Meta description", "type": "string" }, "keywords": { "description": "Meta keywords", "type": "array", "items": { "type": "string" } }, "canonical": { "description": "Canonical URL specified by the page", "type": "string" }, "og_url": { "description": "Open Graph URL", "type": "string" }, "og_title": { "description": "Open Graph title", "type": "string" }, "og_description": { "description": "Open Graph description", "type": "string" }, "og_type": { "description": "Open Graph type (e.g. article, website)", "type": "string" }, "og_site_name": { "description": "Open Graph site name", "type": "string" }, "og_locale": { "description": "Open Graph locale (e.g. en_US)", "type": "string" }, "og_locale_alternate": { "description": "Alternate Open Graph locales", "type": "array", "items": { "type": "string" } }, "og_image": { "description": "Open Graph image URL", "type": "string" }, "author": { "description": "Article author", "type": "string" }, "date_modified": { "description": "Article last-modified date", "type": "string" }, "date_published": { "description": "Article publication date", "type": "string" }, "twitter_site": { "description": "Twitter @username for the site", "type": "string" }, "twitter_card": { "description": "Twitter card type (e.g. summary_large_image)", "type": "string" }, "twitter_description": { "description": "Twitter card description", "type": "string" }, "twitter_title": { "description": "Twitter card title", "type": "string" }, "twitter_image": { "description": "Twitter card image URL", "type": "string" }, "robots": { "description": "Robots meta directive (e.g. noindex, nofollow)", "type": "string" }, "favicon_url": { "description": "Resolved favicon URL for the page (best-effort, from <head> icon hints + manifest)", "nullable": true, "type": "string" } }, "additionalProperties": false }, "response_meta": { "type": "object", "properties": { "usage": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Credits actually charged for this request. Always equals the engine base × the proxy multiplier, plus screenshot_slices. A cache hit has engine \"cache\" (base 0), so it costs only the parts we still had to compute — a newly produced screenshot-slice variant — and is otherwise free." }, "engine": { "type": "string", "enum": [ "http", "browser", "screenshot", "cache" ], "description": "The engine base the request was billed at — \"http\" (1 credit), \"browser\" (3), \"screenshot\" (5), or \"cache\" (0, the result was served from cache) — before the proxy multiplier. Reflects what was delivered, never what was requested." }, "proxy": { "type": "string", "enum": [ "basic", "advanced" ], "description": "The proxy tier that actually resolved the request — the resolved tier, never \"auto\". \"advanced\" multiplies the engine base by 5." }, "screenshot_slices": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Whether this request was billed the screenshot-split add-on: 1 when the screenshot was split on this request (a flat +1 credit outside the proxy multiplier, regardless of how many slices the split produced), else 0 — including a cache hit that reused an already-existing slice variant." } }, "required": [ "credits", "engine", "proxy", "screenshot_slices" ], "additionalProperties": false } }, "required": [ "usage" ], "additionalProperties": false, "description": "Operation metadata for this response (usage/billing)." }, "warnings": { "description": "Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded. `screenshot_unavailable` means a screenshot was requested but, after the browser priority window, the http engine returned the page without one. Stable string codes — clients can switch on them. Warnings are stored with the result and filtered to the fields your request asked for. `metadata_truncated` is retired: metadata no longer has a size budget of its own, so new scrapes never emit it, though it may still appear on results stored before that change.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "requested_url", "response_meta" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "408": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "499": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } } } } }, "/api/usage": { "get": { "tags": [ "Account" ], "description": "Return the current billing cycle usage: total/used/available credits, used quota percentage, max allowed concurrency, and when the cycle resets.", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total credits available for the current billing cycle (plan base + purchased + gifted)." }, "used_credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Credits spent so far in the current billing cycle. May exceed total_credits on plans that allow overages." }, "available_credits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Remaining credits (max(0, total_credits - used_credits)). Clamped to 0 when in overage." }, "used_quota_percent": { "type": "number", "minimum": 0, "description": "Percentage of total_credits used in the current cycle, rounded to 1 decimal. Not capped — values >100 indicate overage." }, "max_concurrency": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Maximum number of concurrent jobs allowed for this organization (plan base + purchased + gifted extras)." }, "usage_reset": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp when the current billing cycle ends and used_credits resets." } }, "required": [ "total_credits", "used_credits", "available_credits", "used_quota_percent", "max_concurrency", "usage_reset" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } } } } }, "/api/whoami": { "get": { "tags": [ "Account" ], "description": "Return the organization name and identifying details of the API token used to authenticate this request.", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_name": { "type": "string", "description": "Display name of the organization that owns the token." }, "token_name": { "type": "string", "description": "User-assigned name of the API token authenticating the request." }, "token_preview": { "type": "string", "description": "Truncated preview of the API token (e.g. `cwbl_…xyz`). Safe to display; does not authenticate." } }, "required": [ "organization_name", "token_name", "token_preview" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "usage_allocation_error", "request_timeout", "invalid_url", "url_too_long", "client_closed_request", "reset_password_token_expired", "user_not_found", "unsupported_url_schema", "url_credentials_not_supported", "blocked_url", "scrape_error", "job_failed", "incorrect_login_method_used", "not_found", "invalid_credentials", "resource_already_exists", "access_denied", "internal_server_error", "service_unavailable", "too_many_requests", "unsupported_content", "unsupported_screenshot_output", "validation_error", "antibot_blocked", "too_many_redirects", "page_too_large" ], "description": "Machine-readable error identifier" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "description": "Additional error-specific details", "oneOf": [ { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "usage_allocation_error" ], "description": "Usage allocation error identifier" }, "reason": { "type": "string", "enum": [ "credit_limit", "concurrency_limit", "duplicate_reservation", "internal_error" ], "description": "Specific reason the allocation was denied" }, "details": { "description": "Current usage and limit details", "type": "object", "properties": { "current_usage": { "description": "Current credit usage in the billing period", "type": "number" }, "current_reserved": { "description": "Credits currently reserved by in-flight jobs", "type": "number" }, "max_credits": { "description": "Credits available in the billing period", "type": "number" }, "current_concurrent": { "description": "Number of currently running concurrent jobs", "type": "number" }, "max_concurrent": { "description": "Maximum concurrent jobs allowed", "type": "number" } }, "additionalProperties": false } }, "required": [ "error_name", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "error_name": { "type": "string", "enum": [ "too_many_requests" ], "description": "Rate limit error identifier" }, "retry_after_ms": { "description": "Suggested wait time in milliseconds before retrying", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limited_by": { "description": "Which rate limit was exceeded (e.g. org, ip)", "type": "string" } }, "required": [ "error_name" ], "additionalProperties": false } ] } }, "required": [ "name", "message" ], "additionalProperties": false } } } } } } } }, "servers": [ { "url": "https://api.crawlbrulee.com" } ] }