{ "openapi": "3.1.0", "info": { "title": "Nimble SDK", "version": "1.0.0", "description": "The AI-Native SDK for Real-Time Web Data at scale" }, "paths": { "/v1/extract": { "post": { "summary": "Extract", "tags": [ "Extract" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ExtractPayload" } ], "examples": [ { "url": "https://www.example.com", "render": true, "country": "US", "locale": "en-US" } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ExtractResponse" } ], "examples": [ { "url": "https://www.example.com/", "task_id": "e8ed8ef6-2657-43ba-98d5-a5c79ea7b551", "status": "success", "status_code": 200, "data": { "html": "...", "markdown": "MARKDOWN", "parsing": {}, "cookies": {}, "screenshot": "iVBORw0KGgoAAAANSUhEUgAAA...", "fetch_request": [], "network_capture": [], "browser_actions": [], "headers": {} }, "metadata": { "query_time": "2026-02-09T10:26:05.817Z", "query_duration": 1877, "response_parameters": { "input_url": "https://www.example.com/" }, "driver": "vx8" } } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/extract/async": { "post": { "summary": "Extract Async", "tags": [ "Extract" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ExtractPayload" }, { "$ref": "#/components/schemas/AsyncOptions" } ], "examples": [ { "url": "https://www.example.com", "render": true, "country": "US", "locale": "en-US", "storage_url": "s3://mu-s3-bucket.com/", "storage_type": "s3", "callback_url": "https://my-callback-url.com/" } ] } } } }, "responses": { "200": { "description": "Async Task Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncResponse" }, "example": { "status": "success", "task": { "id": "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f", "state": "pending", "created_at": "2026-01-24T12:36:24.685Z", "modified_at": "2026-01-24T12:36:24.685Z", "input": {} } } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/extract/batch": { "post": { "summary": "Extract Batch", "tags": [ "Extract" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ExtractBatchPayload" } ], "examples": [ { "inputs": [ { "url": "https://www.example.com/page1" }, { "url": "https://www.example.com/page2" }, { "url": "https://www.example.com/page3" }, { "url": "https://www.example.com/page4" } ], "shared_inputs": { "callback_url": "https://example.com/webhook/callback", "storage_type": "s3", "storage_url": "s3://bucket-name/path/to/object", "storage_compress": true, "storage_object_name": "result-2024-01-15.json", "render": true, "country": "US", "locale": "en-US" } } ] } } } }, "responses": { "200": { "description": "Extract Batch Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" }, "example": { "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "batch_size": 1, "tasks": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "state": "pending", "output_url": "string", "created_at": "2024-01-15T10:30:00Z", "modified_at": "2024-01-15T10:35:00Z", "account_name": "string", "input": null, "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "status_code": 200, "api_type": "extract" } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/agents/run": { "post": { "summary": "Agent Run", "description": "Execute Search Agent Realtime Endpoint", "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AgentPayload" } ], "examples": [ { "agent": "amazon_pdp", "params": { "asin": "B0DLKFK6LR" } } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AgentResponse" } ], "examples": [ { "url": "https://www.example.com/", "task_id": "e8ed8ef6-2657-43ba-98d5-a5c79ea7b551", "status": "success", "status_code": 200, "data": { "html": "...", "markdown": "MARKDOWN", "parsing": {}, "cookies": {}, "screenshot": "iVBORw0KGgoAAAANSUhEUgAAA...", "fetch_request": [], "network_capture": [], "browser_actions": [], "headers": {} }, "metadata": { "query_time": "2026-02-09T10:26:05.817Z", "query_duration": 1877, "response_parameters": { "input_url": "https://www.example.com/" }, "driver": "vx8", "agent": "agent_name" } } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Agent Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "msg": { "type": "string", "examples": [ "Agent not found" ] } }, "required": [ "status", "msg" ] }, "example": { "status": "failed", "msg": "Agent not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/agents/async": { "post": { "summary": "Agent Async", "description": "Execute Search Agent Async Endpoint", "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AgentAsyncPayload" } ], "examples": [ { "agent": "google_search", "params": { "query": "What happened last night in the NBA?", "storage_url": "s3://mu-s3-bucket.com/", "storage_type": "s3", "callback_url": "https://my-callback-url.com/" } } ] } } } }, "responses": { "200": { "description": "Async Task Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncResponse" }, "example": { "status": "success", "task": { "id": "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f", "state": "pending", "created_at": "2026-01-24T12:36:24.685Z", "modified_at": "2026-01-24T12:36:24.685Z", "input": {} } } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Agent Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "msg": { "type": "string", "examples": [ "Agent not found" ] } }, "required": [ "status", "msg" ] }, "example": { "status": "failed", "msg": "Agent not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/agents/batch": { "post": { "summary": "Agent Batch", "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AgentBatchBody" } ], "examples": [ { "inputs": [ { "params": { "keyword": "iphone 15" } }, { "params": { "keyword": "iphone 16" } }, { "params": { "keyword": "iphone 17" } } ], "shared_inputs": { "agent": "amazon_serp" } } ] } } } }, "responses": { "200": { "description": "Agent Batch Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" }, "example": { "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "batch_size": 1, "tasks": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "state": "pending", "output_url": "string", "created_at": "2024-01-15T10:30:00Z", "modified_at": "2024-01-15T10:35:00Z", "account_name": "string", "input": null, "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "status_code": 200, "api_type": "extract" } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/agents/generations": { "post": { "tags": [ "Agents" ], "summary": "Generate Agent", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateAgentGenerationRequest" }, { "$ref": "#/components/schemas/CreateAgentRefinementRequest" } ], "title": "Request", "examples": [ { "prompt": "I want an agent for books.toscrape.com category pages", "agent_name": "books_toscrape_categories_nkjansdkj", "url": "books.toscrape.com", "input_schema": { "type": "object", "properties": { "category": { "type": "string" } } }, "output_schema": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" }, "url": { "type": "string" }, "availability": { "type": "string" } } } } ] } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGenerationResponse" }, "example": { "id": "86441962-c8f5-4c24-b271-ee877d2dd865", "status": "queued", "agent_name": "books_toscrape_categories_nkjansdkj_2026_03_24_zco2isqi", "source_version_id": "c51d09fc-c8f2-4b3a-a9bc-eaab88316217", "created_at": "2026-03-24T19:19:39.300002+00:00" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/agents/generations/{generation_id}": { "get": { "tags": [ "Agents" ], "summary": "Get Generation", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "generation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Generation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGenerationResponse" }, "example": { "id": "86441962-c8f5-4c24-b271-ee877d2dd865", "status": "success", "agent_name": "books_toscrape_categories_nkjansdkj_2026_03_24_zco2isqi", "source_version_id": "c51d09fc-c8f2-4b3a-a9bc-eaab88316217", "generated_version_id": "fee30209-2439-459b-985a-ba7f8d8d2325", "generated_version": { "id": "fee30209-2439-459b-985a-ba7f8d8d2325", "agent_name": "books_toscrape_categories_nkjansdkj_2026_03_24_zco2isqi", "version_number": 2, "metadata": { "vertical": "Other", "data_source": "books.toscrape.com", "display_name": "books_toscrape_categories_nkjansdkj", "tags": [], "domain": "books.toscrape.com", "is_displayed": false }, "steps": [], "artifacts": {} }, "summary": "Done! The agent for **books.toscrape.com** category pages is fully configured and preview ran successfully. Here's a summary of what was set up:\n\n- **Browsing**: Navigates to category pages using a URL template with `category_slug` and `category_id` as inputs (e.g., `mystery` / `3`)\n- **Parsing**: Extracts book data — `name`, `price`, `url`, and `availability` — from each listing on the category page", "created_at": "2026-03-24T19:19:39.300002+00:00", "started_at": "2026-03-24T19:19:39.307295+00:00", "completed_at": "2026-03-24T19:22:01.638660+00:00" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "422": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/agents": { "get": { "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "summary": "List Agents", "parameters": [ { "name": "privacy", "in": "query", "required": false, "schema": { "description": "Filter by privacy level", "default": "all", "type": "string", "enum": [ "public", "private", "all" ] }, "description": "Filter by privacy level" }, { "name": "managed_by", "in": "query", "required": false, "schema": { "description": "Filter by who manage the agent", "type": "string", "enum": [ "nimble", "community", "self_managed" ] }, "description": "Filter by who manage the agent" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 250, "minimum": 1, "description": "Number of results per page", "default": 100, "title": "Limit" }, "description": "Number of results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "type": "array", "items": { "properties": { "name": { "type": "string", "title": "Name" }, "is_public": { "type": "boolean", "title": "Is Public" }, "managed_by": { "type": "string", "title": "Managed By" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "vertical": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vertical" }, "entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Type" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" } }, "type": "object", "required": [ "name", "is_public", "display_name" ], "title": "Agents" }, "title": "Response List Agents" } ], "examples": [ [ { "name": "aldi_clp", "is_public": true, "display_name": "Aldi Category Landing Page", "description": "The Aldi Browse Products agent extracts structured product listings from Aldi’s category pages. This agent is ideal for monitoring category-level assortment, analyzing competitive inventory, and powering product discovery and pricing intelligence use cases", "vertical": "Ecommerce", "entity_type": "Category Landing Page (CLP)", "domain": "www.aldi.us", "managed_by": "nimble" }, { "name": "aldi_pdp", "is_public": true, "display_name": "Aldi Product Details Page", "description": "The Aldi Product Detail Page Agent extracts structured data from individual product pages on Aldi. This agent is ideal for tracking competitor pricing, monitoring catalog changes, and powering product intelligence use cases.\n", "vertical": "Ecommerce", "entity_type": "Product Detail Page (PDP)", "domain": "https://www.aldi.us/", "managed_by": "nimble" }, { "name": "amazon_plp", "is_public": true, "display_name": "Amazon CLP", "description": "The Amazon Browse Products agent extracts structured product listings from Amazon’s category pages. This agent is ideal for monitoring category-level assortment, analyzing competitive inventory, and powering product discovery and pricing intelligence use cases", "vertical": "Ecommerce", "entity_type": "Category Landing Page (CLP)", "domain": "www.amazon.com", "managed_by": "nimble" }, { "name": "amazon_pdp", "is_public": true, "display_name": "Amazon Product Details Page", "description": "The Amazon Product Detail Page Agent extracts structured data from individual product pages on Amazon. This agent is ideal for tracking competitor pricing, monitoring catalog changes, and powering product intelligence use cases.", "vertical": "Ecommerce", "entity_type": "Product Detail Page (PDP)", "domain": "www.amazon.com", "managed_by": "nimble" } ] ] } } } } } } }, "/v1/agents/{agent_name}": { "get": { "tags": [ "Agents" ], "security": [ { "BearerAuth": [] } ], "summary": "Get Agent Details", "parameters": [ { "name": "agent_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "properties": { "name": { "type": "string", "title": "Name" }, "is_public": { "type": "boolean", "title": "Is Public" }, "managed_by": { "type": "string", "title": "Managed By" }, "display_name": { "type": "string", "title": "Display Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "vertical": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vertical" }, "entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Type" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "input_properties": { "anyOf": [ { "items": { "properties": { "name": { "type": "string", "title": "Name", "default": "" }, "required": { "type": "boolean", "title": "Required", "default": false }, "type": { "type": "string", "title": "Type", "default": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "is_localization_param": { "type": "boolean", "title": "Is Localization Param", "default": false }, "is_pagination_param": { "type": "boolean", "title": "Is Pagination Param", "default": false }, "rules": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Rules" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples" }, "default": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default" } }, "type": "object", "title": "AgentInputProperty" }, "type": "array" }, { "type": "null" } ], "title": "Input Properties" }, "feature_flags": { "properties": { "is_localization_supported": { "type": "boolean", "title": "Is Localization Supported", "default": false }, "is_pagination_supported": { "type": "boolean", "title": "Is Pagination Supported", "default": false } }, "type": "object", "title": "FeatureFlags" } }, "type": "object", "required": [ "name", "is_public", "display_name" ], "title": "FullAgent" } ], "examples": [ { "name": "amazon_pdp", "is_public": true, "display_name": "Amazon Product Details Page", "description": "The Amazon Product Detail Page Agent extracts structured data from individual product pages on Amazon. This agent is ideal for tracking competitor pricing, monitoring catalog changes, and powering product intelligence use cases.", "vertical": "Ecommerce", "entity_type": "Product Detail Page (PDP)", "domain": "www.amazon.com", "managed_by": "nimble", "output_schema": { "product_title": { "type": "string", "description": "The name of the product" }, "manufacturer": { "type": "string", "description": "The company that manufactured the product" }, "product_url": { "type": "string", "description": "The direct Amazon URL of the product" }, "pack_size": { "type": "string", "description": "The packaging or pack size information (e.g., 12-pack, 500ml)" }, "web_price": { "type": "number", "description": "The current selling price of the product in USD" }, "product_detail_column_and_information_within_table": { "type": "array", "description": "Tabular details about the product such as specifications or attributes", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" } } } }, "product_availability_and_delivery_terms": { "type": "string", "description": "Shipping terms, delivery times, or availability details" }, "unit_of_measure": { "type": "string", "description": "Unit of measurement for the product (e.g., oz, lb, ml, pack)" }, "unit_of_measure_quantity": { "type": "number", "description": "Numeric quantity of the product in the specified unit of measure" }, "selection_for_type_of_item_field": { "type": "string", "description": "Primary selection option field label (e.g., Size, Color)" }, "selection_for_type_of_item_field_entry": { "type": "string", "description": "The selected value for the primary selection field" }, "secondary_selection_for_type_of_item_field": { "type": "string", "description": "Secondary selection option field label (if applicable)" }, "secondary_selection_for_type_of_item_field_entry": { "type": "string", "description": "The selected value for the secondary selection field" }, "list_price": { "type": "number", "description": "The original price (before discounts) of the product in USD" }, "product_hierarchy": { "type": "array", "description": "Breadcrumb navigation path or category hierarchy for the product", "items": { "type": "string" } }, "reviews_statistics_percentage_five_to_zero": { "type": "object", "description": "Distribution of customer ratings (5-star through 0-star)", "properties": { "5_star": { "type": "string" }, "4_star": { "type": "string" }, "3_star": { "type": "string" }, "2_star": { "type": "string" }, "1_star": { "type": "string" } } }, "review_scale": { "type": "number", "description": "Numerical rating scale used (usually 5)" }, "availability": { "type": "boolean", "description": "Whether the product is in stock (true) or out of stock (false)" }, "image_url": { "type": "string", "description": "The URL of the product's main image", "format": "uri" }, "brand": { "type": "string", "description": "The brand name of the product" }, "product_description": { "type": "string", "description": "Detailed text description of the product" }, "publisher": { "type": "string", "description": "The publisher, distributor, or entity responsible for listing the product" }, "average_of_reviews": { "type": "number", "minimum": 0, "maximum": 5, "description": "The average customer rating (0 to 5 stars)" }, "number_of_reviews": { "type": "number", "description": "The total number of customer reviews for the product" }, "sold_by": { "type": "string", "description": "The entity or seller offering the product" }, "direct": { "type": "boolean", "description": "If seller is Amazon" }, "ships_from": { "type": "string", "description": "The fulfillment source or warehouse shipping the product" }, "payment": { "type": "string", "description": "Available payment methods or terms" }, "packaging": { "type": "string", "description": "Product packaging details (e.g., box, bag, recyclable packaging)" }, "amazons_choice": { "type": "boolean", "description": "Whether the product is marked as Amazon's Choice" }, "best_sellers_category_1_name": { "type": "string", "description": "The name of the primary Best Seller category" }, "best_sellers_category_1_rank": { "type": "string", "description": "The Best Seller rank of the product within the primary category" }, "best_sellers_category_2_name": { "type": "string", "description": "The name of the secondary Best Seller category" }, "best_sellers_category_2_rank": { "type": "string", "description": "The Best Seller rank of the product within the secondary category" }, "climate_pledge_friendly": { "type": "boolean", "description": "Indicates if the product is part of Amazon's Climate Pledge Friendly program" }, "warning": { "type": "string", "description": "Product warnings (e.g., choking hazard, safety notes)" }, "special_feature": { "type": "string", "description": "Unique feature or benefit of the product" }, "variants": { "type": "array", "description": "ASINs of related or variant products (e.g., other colors or sizes)", "items": { "type": "string" } }, "brief_product_description": { "type": "array", "description": "Bullet-point features or highlights of the product", "items": { "type": "string" } }, "size": { "type": "string", "description": "Dimensions or size specification (LxWxH)" }, "color": { "type": "string", "description": "Color of the product" }, "material": { "type": "string", "description": "Material composition of the product" }, "recommended_uses": { "type": "string", "description": "Suggested uses or scenarios for the product" }, "model": { "type": "string", "description": "Manufacturer's model number" }, "country_of_origin": { "type": "string", "description": "Country where the product was manufactured" }, "asin": { "type": "string", "description": "Amazon Standard Identification Number (ASIN) of the product" }, "customers_say": { "type": "string", "description": "AI-generated summary of customer feedback" }, "top_reviews": { "type": "array", "description": "Top reviews for the product (typically the most helpful or recent ones)", "items": { "type": "object", "properties": { "stars": { "type": "number" }, "review_title": { "type": "string" }, "review_body": { "type": "string" } } } }, "technical_details": { "type": "array", "description": "Technical specifications or details of the product", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } }, "brand_logo": { "type": "string", "description": "URL of the brand's logo" }, "brand_story_background": { "type": "string", "description": "URL of the background image behind the brand logo" }, "brand_description": { "type": "string", "description": "Text description of the brand" }, "brand_store": { "type": "string", "description": "URL of the brand's Amazon store page" }, "bought_in_past_month": { "type": "string", "description": "Recent sales trends, e.g., number of units bought in the past month" }, "frequently_bought_with": { "type": "object", "description": "Items that are commonly purchased alongside this product", "properties": { "total_price": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string" }, "title": { "type": "string" }, "asin": { "type": "string" } } } } } }, "long_text": { "type": "string" }, "alternatives": { "type": "array", "description": "Alternative products available on Amazon", "items": { "type": "object", "properties": { "asin": { "type": "string" }, "price": { "type": "string" }, "title": { "type": "string" } } } }, "4_stars_and_above": { "type": "array", "description": "Similar products with ratings of 4 stars or higher", "items": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "string" }, "asin": { "type": "string" } } } }, "related_products": { "type": "array", "description": "Other products related to this item", "items": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "string" }, "asin": { "type": "string" } } } }, "related_products_free_delivery": { "type": "array", "description": "Related products with free delivery eligibility", "items": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "string" }, "asin": { "type": "string" } } } }, "alternate_products_for_top_3_alternates": { "type": "object", "description": "Details about substitute products for top 3 alternates", "properties": { "product_1_product_description": { "type": "string", "description": "Title/description text for alternate product #1." }, "product_1_url": { "type": "string", "description": "Canonical Amazon ASIN URL for product #1 (e.g., https://www.amazon.com/dp/...)." }, "product_1_web_price": { "type": "string", "description": "Displayed price text for product #1 (as extracted, including currency symbol)." }, "product_1_feature": { "type": "string", "description": "Feature/attribute name for product #1." }, "product_1_feature_value": { "type": "string", "description": "Value for the feature/attribute of product #1." }, "product_2_product_description": { "type": "string", "description": "Title/description text for alternate product #2." }, "product_2_url": { "type": "string", "description": "Canonical Amazon ASIN URL for product #2 (e.g., https://www.amazon.com/dp/...)." }, "product_2_web_price": { "type": "string", "description": "Displayed price text for product #2 (as extracted, including currency symbol)." }, "product_2_feature": { "type": "string", "description": "Feature/attribute name for product #2." }, "product_2_feature_value": { "type": "string", "description": "Value for the feature/attribute of product #2." }, "product_3_product_description": { "type": "string", "description": "Title/description text for alternate product #3." }, "product_3_url": { "type": "string", "description": "Canonical Amazon ASIN URL for product #3 (e.g., https://www.amazon.com/dp/...)." }, "product_3_web_price": { "type": "string", "description": "Displayed price text for product #3 (as extracted, including currency symbol)." }, "product_3_feature": { "type": "string", "description": "Feature/attribute name for product #3." }, "product_3_feature_value": { "type": "string", "description": "Value for the feature/attribute of product #3." } } }, "alternate_product_1_product_description": { "type": "string", "description": "Description of the first alternate product" }, "alternate_product_1_product_url": { "type": "string", "description": "URL of the first alternate product" }, "alternate_product_1_web_price": { "type": "string", "description": "Price of the first alternate product" }, "alternate_product_1_feature": { "type": "string", "description": "Highlighted feature of the first alternate product" }, "alternate_product_1_feature_value": { "type": "string", "description": "Value associated with the feature of the first alternate product" }, "feature": { "type": "string", "description": "Generic feature name of the product" }, "feature_value": { "type": "string", "description": "Value corresponding to the generic product feature" }, "UNSPSC": { "type": "string", "description": "The UNSPSC classification code for the product" }, "agent_zip_code": { "type": "string", "description": "ZIP code of the responsible shipping agent or warehouse" }, "climate_pledge_certification": { "type": "string", "description": "Certification name associated with Climate Pledge Friendly" }, "UPC": { "type": "string", "description": "Universal Product Code (UPC) for the item" }, "shipping_weight": { "type": "string", "description": "Weight of the product used for shipping calculations" }, "product_dimensions": { "type": "string", "description": "Dimensions of the product package" }, "suggested_use": { "type": "string", "description": "Suggested application or use instructions" }, "extra_savings": { "type": "string", "description": "Additional savings offers available on the product" }, "savings": { "type": "string", "description": "Current discount or savings on the product" }, "subscribe_and_save": { "type": "boolean", "description": "Whether Subscribe & Save is available" }, "subscribe_and_save_details": { "type": "string", "description": "Details about the Subscribe & Save program for this product" }, "buy_x_get_y": { "type": "string", "description": "Buy-one-get-one or similar promotional offers" }, "has_a_plus_section": { "type": "boolean", "description": "Whether the product page includes an A+ Content section" }, "a_plus_headers": { "type": "array", "description": "Headers from A+ content sections", "items": { "type": "string" } }, "scent": { "type": "string", "description": "Fragrance or scent of the product" }, "cel_widgets": { "type": "array", "description": "Widgets or modules included on the product detail page", "items": { "type": "string" } }, "subscription_price": { "type": "string", "description": "Discounted price for subscription orders" }, "visible_images_count": { "type": "array", "description": "Number and details of visible images on the product page", "items": { "type": "string" } }, "deal_description": { "type": "string", "description": "Details of any ongoing deals or promotions" }, "sun_protection": { "type": "string", "description": "Level or type of sun protection (e.g., SPF 30)" }, "bundle_asins": { "type": "array", "description": "ASINs of items sold together as a bundle", "items": { "type": "string" } }, "video_count": { "type": "number", "description": "Number of product videos available on the listing" }, "shipping_amount": { "type": "string", "description": "Shipping cost for the product" }, "reviews_ai_summary": { "type": "string", "description": "AI-generated summary of customer reviews" }, "review_mentions_with_positive_sentiment": { "type": "array", "description": "Review mentions categorized with positive sentiment", "items": { "type": "string" } }, "review_mentions_with_neutral_sentiment": { "type": "array", "description": "Review mentions categorized with neutral sentiment", "items": { "type": "string" } }, "review_mentions_with_negative_sentiment": { "type": "array", "description": "Review mentions categorized with negative sentiment", "items": { "type": "string" } }, "replenishment_frequency_common": { "type": "string", "description": "Most common replenishment frequency (e.g., every month)" }, "replenishment_frequency_options": { "type": "array", "description": "List of available replenishment frequency options", "items": { "type": "string" } }, "option_name": { "type": "string", "description": "The name of a selectable product option" }, "similar_item": { "type": "string", "description": "A product identified as similar to this one" }, "sponsored_item": { "type": "string", "description": "Sponsored product promoted alongside the listing" }, "delivery_time_estimate": { "type": "string", "description": "Estimated delivery time for the product" }, "variations": { "type": "array", "description": "Different variations of the product (size, color, etc.)", "items": { "type": "string" } }, "uom": { "type": "string", "description": "Unit of Measure" }, "uomq": { "type": "number", "description": "Unit of Measure Quantity" }, "moq": { "type": "number", "description": "Minimum Order Quantity" }, "moq_price": { "type": "string", "description": "Minimum Order Quantity Price" }, "shipping_time": { "type": "string", "description": "Estimated shipping time for the product" }, "store_location": { "type": "string", "description": "Store location in scrape context." }, "price_per_unit": { "type": "number", "description": "Price of 1 unit in pack." }, "promos": { "type": "array", "description": "List of promotional sales and deals" }, "coupons": { "type": "array", "description": "List of available coupons for this product" }, "badges": { "type": "array", "description": "List of product badges as displayed below the product title" } }, "input_properties": [ { "name": "asin", "required": true, "type": "string", "description": "Product ID", "rules": [ "minLength: 1" ], "examples": [ "B0DLKFK6LR", "B0177IUSTK", "B01N1N64V2", "B0B9RTKR72", "B0DQYPYVB6", "B06XC9321S", "B09RX4HKTD", "B082T6P545", "B08NWK2P1J", "B004MFME2G" ], "default": null, "is_localization_param": false, "is_pagination_param": false }, { "name": "zip_code", "required": false, "type": "string", "description": "Zip code for location", "rules": [ "minLength: 1" ], "examples": null, "default": "90210", "is_localization_param": true, "is_pagination_param": false } ], "feature_flags": { "is_localization_supported": true, "is_pagination_supported": false } } ] } } } } } } }, "/v1/search": { "post": { "summary": "Search", "tags": [ "Search" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchPayload" } ], "examples": [ { "query": "Nike brand perception consumer reviews 2025", "focus": "social", "max_results": 10 } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchResponse" } ], "examples": [ { "total_results": 10, "results": [ { "title": "Top 10 Web Scraping Tools for 2024", "description": "Comprehensive guide to the best web scraping tools...", "url": "https://example.com/article1", "content": "Full parsed content from the page...", "metadata": { "published_date": "2024-01-15" } }, { "title": "Web Scraping Tools Comparison", "description": "Compare features, pricing, and performance...", "url": "https://example2.com/comparison", "content": "Full parsed content from the page...", "metadata": {} } ], "request_id": "123e4567-e89b-12d3-a456-426614174000" } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/map": { "post": { "summary": "Map", "tags": [ "Map" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MapPayload" } ], "examples": [ { "url": "https://example.com", "sitemap": "include", "country": "US", "locale": "en-US", "domain_filter": "all", "limit": 100 } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MapResponse" } ], "examples": [ { "task_id": "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3", "success": true, "links": [ { "title": "Web Scraping API", "url": "https://www.example.com/page1", "description": "Complete guide to web scraping" }, { "url": "https://www.nimbleway.com/nimble-api/web" }, { "title": "API Documentation", "url": "https://www.example.com/docs" } ] } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/tasks": { "get": { "summary": "List tasks", "description": "Retrieve a paginated list of tasks for the authenticated account.", "tags": [ "Tasks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "description": "Cursor for pagination. Use the next_cursor from the previous response.", "type": "string", "format": "uuid" }, "description": "Cursor for pagination. Use the next_cursor from the previous response." }, { "in": "query", "name": "limit", "schema": { "default": 100, "description": "Number of tasks to return per page.", "examples": [ 10 ], "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Number of tasks to return per page." } ], "responses": { "200": { "description": "List of tasks returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskListResponse" }, "example": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "state": "pending", "output_url": "string", "status_url": "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000", "download_url": "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results", "error": "Connection timeout", "error_type": "timeout_error", "created_at": "2024-01-15T10:30:00Z", "modified_at": "2024-01-15T10:35:00Z", "account_name": "string", "input": null, "_query": null, "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "status_code": 200, "api_type": "web" } ], "pagination": { "has_next": true, "next_cursor": "string", "total": 1 } } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Task Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Task not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Task not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/tasks/{task_id}": { "get": { "summary": "Task Status", "description": "Retrieve the status and results of an async task by ID. Works for all async task types (extract, search, map, agent, crawl).", "tags": [ "Tasks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the async task", "examples": [ "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f" ] }, "required": true, "description": "The unique identifier of the async task" } ], "responses": { "200": { "description": "Task Details with Results", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "success" ] }, "task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique task identifier" }, "state": { "type": "string", "description": "Current state of the task", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Task creation timestamp" }, "modified_at": { "type": "string", "format": "date-time", "description": "Task last modification timestamp" }, "input": { "type": "object", "description": "Original request input parameters" }, "result": { "type": "object", "description": "Task results (structure varies by method used). Only present when state is 'completed'." } } } }, "description": "Task details including metadata and results. The 'result' field structure varies based on method used (extract, search, map, agent, or crawl)." }, "example": { "status": "success", "task": { "id": "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f", "state": "completed", "created_at": "2026-01-24T12:36:24.685Z", "modified_at": "2026-01-24T12:37:30.123Z", "input": { "url": "https://example.com" } } } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Task Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Task not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Task not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/tasks/{task_id}/results": { "get": { "summary": "Task Result", "description": "Retrieve the status and results of an async task by ID. Works for all async task types (extract, search, map, agent, crawl).", "tags": [ "Tasks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the async task", "examples": [ "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f" ] }, "required": true, "description": "The unique identifier of the async task" } ], "responses": { "200": { "description": "Async Task Results", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AgentResponse" }, { "$ref": "#/components/schemas/ExtractResponse" } ], "examples": [ { "url": "https://www.example.com/", "task_id": "e8ed8ef6-2657-43ba-98d5-a5c79ea7b551", "status": "success", "status_code": 200, "data": { "html": "...", "markdown": "MARKDOWN", "parsing": {}, "cookies": {}, "screenshot": "iVBORw0KGgoAAAANSUhEUgAAA...", "fetch_request": [], "network_capture": [], "browser_actions": [], "headers": {} }, "metadata": { "query_time": "2026-02-09T10:26:05.817Z", "query_duration": 1877, "response_parameters": { "input_url": "https://www.example.com/" }, "driver": "vx8" } } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Task Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Task not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Task not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/batches": { "get": { "summary": "List batches", "description": "Retrieve a paginated list of batches for the authenticated account.", "tags": [ "Tasks" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of batches returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListResponse" }, "example": { "data": [ { "id": "69c41d24-cc43-4ffa-b225-d46a8599ec4e", "account_name": "account_name", "completed": false, "created_at": "2026-03-24T14:27:57.642Z", "tasks": [ "afe1af62-a361-4df0-ba30-126842aba6d2", "e42562aa-45fc-404b-a088-616fbf1daeb2" ], "username": "admin" }, { "id": "31f260da-237a-4f6f-adbd-528f37d0e3e0", "account_name": "account_name", "completed": false, "created_at": "2026-03-24T14:28:17.003Z", "tasks": [ "58821233-9b4c-43de-b4ba-816a8f053e1f", "7f6c6d61-fbc1-4bc1-abc1-211b28c38927" ], "username": "admin" } ], "pagination": { "has_next": false, "next_cursor": null, "total": 2 } } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Batch Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Batch not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Batch not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/batches/{batch_id}": { "get": { "summary": "Get batch details", "description": "Retrieve the details of a batch including all its tasks and completion status.", "tags": [ "Tasks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "batch_id", "schema": { "type": "string", "description": "The unique identifier of the batch.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "required": true, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Batch found and returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchGetResponse" }, "example": { "status": "success", "id": "string", "completed": true, "completed_count": 1, "progress": 1, "created_at": "string", "completed_at": "string", "tasks": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "state": "pending", "output_url": "string", "status_url": "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000", "download_url": "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results", "error": "Connection timeout", "error_type": "timeout_error", "created_at": "2024-01-15T10:30:00Z", "modified_at": "2024-01-15T10:35:00Z", "account_name": "string", "input": null, "_query": null, "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "status_code": 200, "api_type": "web" } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Batch Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Batch not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Batch not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/batches/{batch_id}/progress": { "get": { "summary": "Get batch progress", "description": "Retrieve lightweight progress information for a batch without fetching all task details.", "tags": [ "Tasks" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "batch_id", "schema": { "type": "string", "description": "The unique identifier of the batch.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "required": true, "description": "The unique identifier of the batch." } ], "responses": { "200": { "description": "Batch progress returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchProgressResponse" }, "example": { "status": "success", "id": "string", "completed": true, "completed_count": 1, "completed_at": "string", "progress": 1 } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Batch Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Batch not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Batch not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/crawl": { "post": { "summary": "Create Crawl", "tags": [ "Crawl" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CrawlPayload" } ], "examples": [ { "url": "https://example.com", "name": "my-crawler-1", "sitemap": "include", "limit": 100, "max_discovery_depth": 3 } ] } } } }, "responses": { "200": { "description": "Successful Response - Crawl Task Created", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Optional name for the crawl task" }, "account_name": { "type": "string", "nullable": true, "description": "The user's account name" }, "url": { "type": "string", "format": "uri", "description": "Starting URL for the crawl" }, "crawl_options": { "type": "object", "description": "Crawl configuration settings applied to this task", "properties": { "limit": { "type": "integer" }, "sitemap": { "type": "string", "enum": [ "skip", "include", "only" ] }, "allow_subdomains": { "type": "boolean" }, "crawl_entire_domain": { "type": "boolean" }, "max_discovery_depth": { "type": "integer" }, "allow_external_links": { "type": "boolean" }, "ignore_query_parameters": { "type": "boolean" } } }, "extract_options": { "type": "object", "nullable": true, "description": "Optional extraction configuration for each crawled page" }, "crawl_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the crawl task" }, "status": { "type": "string", "description": "Current status of the crawl task", "enum": [ "queued", "running", "completed", "failed" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the crawl task was created" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the crawl was completed (null if not completed)" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the crawl was updateded" } }, "required": [ "crawl_id", "url", "crawl_options", "status", "created_at" ] } ], "examples": [ { "crawl_id": "85b21e98-69c5-4aa5-9d25-261a55bbf0db", "name": "my-crawler-1", "url": "https://www.amazon.com/dp", "status": "queued", "account_name": "ACCOUNT_NAME", "created_at": "2026-02-11T13:55:45.512Z", "updated_at": "2026-02-11T13:55:45.512Z", "completed_at": null, "crawl_options": { "sitemap": "include", "crawl_entire_domain": false, "limit": 10, "max_discovery_depth": 5, "ignore_query_parameters": false, "allow_external_links": false, "allow_subdomains": false }, "extract_options": null } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } }, "get": { "summary": "List Crawls", "tags": [ "Crawl" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "canceled" ], "description": "Filter crawls by their status", "examples": [ "pending" ] }, "required": true, "description": "Filter crawls by their status" }, { "in": "query", "name": "cursor", "schema": { "description": "Cursor for pagination", "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "description": "Cursor for pagination" }, { "in": "query", "name": "limit", "schema": { "description": "Number of crawls to return per page", "examples": [ 10 ], "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Number of crawls to return per page" } ], "responses": { "200": { "description": "Successful Response - List of Crawl Tasks", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "description": "Array of crawl tasks", "items": { "type": "object", "properties": { "crawl_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the crawl task" }, "name": { "type": "string", "nullable": true, "description": "Optional name for the crawl task" }, "url": { "type": "string", "format": "uri", "description": "Starting URL for the crawl" }, "account_name": { "type": "string", "nullable": true, "description": "The user's account name" }, "status": { "type": "string", "description": "Current status of the crawl task", "enum": [ "pending", "running", "completed", "failed", "canceled" ] }, "total": { "type": "integer", "nullable": true, "description": "Total number of pages discovered" }, "completed": { "type": "integer", "nullable": true, "description": "Number of pages completed" }, "failed": { "type": "integer", "nullable": true, "description": "Number of pages failed" }, "pending": { "type": "integer", "nullable": true, "description": "Number of pages pending" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the crawl task was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the crawl task was updateded" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the crawl was completed" }, "crawl_options": { "type": "object", "description": "Crawl configuration settings" }, "extract_options": { "type": "object", "nullable": true, "description": "Optional extraction configuration" }, "tasks": { "type": "array", "description": "Array of individual page crawl tasks", "items": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "examples": [ "abc12345-e89b-12d3-a456-426614174001" ] }, "status": { "type": "string", "examples": [ "completed" ], "enum": [ "pending", "failed", "completed" ] }, "completed_at": { "type": "string", "description": "Timestamp when task was completed" }, "updated_at": { "type": "string", "description": "Timestamp when task was updateded" } } } } } } }, "pagination": { "type": "object", "description": "Pagination information", "properties": { "hasNext": { "type": "boolean", "description": "Whether there are more results available" }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor for the next page of results" }, "total": { "type": "integer", "description": "Total number of crawl tasks matching the filter" } } } }, "required": [ "data", "pagination" ] } ], "examples": [ { "data": [ { "crawl_id": "0e9984a1-980c-412d-9e95-ebe5f6704d8a", "name": "crawl_name", "url": "https://docs.nimbleway.com", "account_name": "account_name", "status": "queued", "total": 2, "completed": 2, "pending": 0, "failed": 0, "created_at": "2026-01-24T11:55:24.197Z", "completed_at": null, "crawl_options": { "limit": 5000, "sitemap": "include", "allow_subdomains": false, "crawl_entire_domain": false, "max_discovery_depth": 5, "allow_external_links": false, "ignore_query_parameters": false }, "extract_options": {}, "tasks": [ { "task_id": "441e0939-064a-4945-b49d-038772fcce17", "status": "completed", "created_at": "2026-02-05T10:34:21.487Z", "updated_at": "2026-02-05T10:34:26.674Z" }, { "task_id": "0b1351e9-8155-4cd2-8cc5-a7528d0692d4", "status": "completed", "created_at": "2026-02-05T10:34:26.667Z", "updated_at": "2026-02-05T10:34:27.733Z" } ] } ], "pagination": { "has_next": false, "next_cursor": null, "total": 15 } } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/crawl/{id}": { "get": { "summary": "Crawl by ID", "tags": [ "Crawl" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the crawl task", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "required": true, "description": "The unique identifier of the crawl task" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the crawl task", "examples": [ "succeeded" ] }, "crawl_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the crawl task", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "name": { "type": "string", "description": "Name of the crawl task" }, "account_name": { "type": "string", "description": "The user's account name" }, "total": { "type": "integer", "description": "Total number of pages to crawl", "examples": [ 10 ] }, "completed": { "type": "integer", "description": "Number of pages completed", "examples": [ 2 ] }, "failed": { "type": "integer", "description": "Number of pages failed", "examples": [ 2 ] }, "pending": { "type": "integer", "description": "Number of pages pending", "examples": [ 2 ] }, "created_at": { "type": "string", "description": "Timestamp when crawl was created" }, "completed_at": { "type": "string", "description": "Timestamp when crawl was completed" }, "updated_at": { "type": "string", "description": "Timestamp when crawl was updateded" }, "tasks": { "type": "array", "description": "Array of individual page crawl tasks", "items": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "examples": [ "abc12345-e89b-12d3-a456-426614174001" ] }, "status": { "type": "string", "examples": [ "completed" ], "enum": [ "pending", "failed", "completed" ] }, "completed_at": { "type": "string", "description": "Timestamp when task was completed" }, "updated_at": { "type": "string", "description": "Timestamp when task was updateded" } }, "required": [ "task_id", "url" ] } } }, "required": [ "status", "crawl_id", "name", "total", "completed", "created_at", "completed_at", "tasks" ] } ], "examples": [ { "crawl_id": "85b21e98-69c5-4aa5-9d25-261a55bbf0db", "name": "my-crawler-1", "url": "https://www.amazon.com/dp", "account_name": "account_name", "status": "succeeded", "completed_at": "2026-02-11T13:57:27.549Z", "crawl_options": { "limit": 10, "sitemap": "include", "allow_subdomains": false, "crawl_entire_domain": false, "max_discovery_depth": 5, "allow_external_links": false, "ignore_query_parameters": false }, "extract_options": null, "created_at": "2026-02-11T13:55:45.512Z", "updated_at": "2026-02-11T13:57:27.555Z", "pending": 0, "completed": 3, "failed": 1, "total": 4, "tasks": [ { "task_id": "8d2bb2fc-e469-4549-b5d8-0d307352aeb5", "status": "completed", "created_at": "2026-02-11T13:55:45.846Z", "updated_at": "2026-02-11T13:55:52.138Z" }, { "task_id": "f1fc1a7d-588b-4c9c-b6f3-00a00b6796ce", "status": "completed", "created_at": "2026-02-11T13:55:52.115Z", "updated_at": "2026-02-11T13:55:53.335Z" }, { "task_id": "79389a76-7c7f-4d6d-9041-c13ff83dc265", "status": "completed", "created_at": "2026-02-11T13:55:52.115Z", "updated_at": "2026-02-11T13:55:53.858Z" }, { "task_id": "7f10be27-a526-4cbb-8330-53c7871e7572", "status": "failed", "created_at": "2026-02-11T13:55:46.075Z", "updated_at": "2026-02-11T13:57:27.534Z" } ] } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Crawl Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Crawl not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Crawl not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } }, "delete": { "summary": "Cancel Crawl", "tags": [ "Crawl" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the crawl task", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "required": true, "description": "The unique identifier of the crawl task" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "canceled" ] } }, "required": [ "status" ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Crawl Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "error": { "type": "string", "examples": [ "Crawl not found" ] } }, "required": [ "status", "error" ] }, "example": { "status": "failed", "error": "Crawl not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/media": { "post": { "summary": "Media Download", "tags": [ "Media" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MediaPayload" } ], "examples": [ { "url": "https://example.com/product-image.jpg", "country": "US", "locale": "en-US", "expected_mime_types": [ "image/*" ] } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/media/async": { "post": { "summary": "Media Download Async", "tags": [ "Media" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MediaPayload" }, { "$ref": "#/components/schemas/AsyncOptions" } ], "examples": [ { "url": "https://example.com/product-image.jpg", "country": "US", "locale": "en-US", "expected_mime_types": [ "image/*" ], "storage": { "url": "s3://my-bucket/media/", "type": "s3", "object_name": "my-image" } } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AsyncResponse" } ], "examples": [ { "status": "success", "task": { "id": "52907745-7672-470e-1231-a2f8feb52944", "state": "pending", "created_at": "2026-03-02T12:00:00.000Z", "modified_at": "2026-03-02T12:00:00.000Z", "account_name": "my-account", "api_type": "media", "input": { "url": "https://example.com/product-image.jpg", "country": "US", "locale": "en-US", "expected_mime_types": [ "image/*" ], "storage": { "url": "s3://my-bucket/media/", "type": "s3", "object_name": "product-123" } } } } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/realtime/serp": { "post": { "servers": [ { "url": "https://api.us.webit.live/api", "description": "Production" } ], "summary": "Fast Google SERP", "tags": [ "Fast SERP" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/FastSerpPayload" } ], "examples": [ { "search_engine": "google_search", "query": "NBA Allstar 2026", "country": "US", "locale": "en" } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SerpResponse" } ], "examples": [ { "url": "https://www.google.com/search?hl=en&gl=us&q=NBA+Allstar+2026", "task_id": "bd46cd9c-50f7-4736-9c4a-660a32e4dc87", "status": "success", "query_time": "2026-03-05T13:47:16.435Z", "html_content": "...", "status_code": 200, "parsing": { "entities": { "AnswerBox": [ { "entity_type": "AnswerBox", "snippet": "NBANBA", "snippet_highlighted": [ "NBANBA" ], "display_link": "" } ], "InlineImages": [ { "entity_type": "InlineImages", "title": "#NBAAllStar 2026: Day of Service with Habitat for Humanity & Baby2Baby", "url": "https://www.youtube.com/watch?v=CG98tKo" } ], "OrganicResult": [ { "position": 1, "title": "2026 All-Star | Schedule", "url": "https://www.nba.com/allstar/2026/schedule", "snippet": "The 2026 NBA All-Star Game will take place on Sunday, Feb. 15, 2026 in Los Angeles, California at the Intuit Dome, the home of the LA Clippers.", "cleaned_domain": "nba", "displayed_url": "https://www.nba.com › allstar › 2026 › schedule", "entity_type": "OrganicResult" }, { "position": 2, "title": "2026 All-Star | Roster", "url": "https://www.nba.com/allstar/2026/roster", "snippet": "2026 All-Star · Latest · Events. Feb. 13: Ruffles All-Star Celebrity Game ...", "cleaned_domain": "nba", "displayed_url": "https://www.nba.com › allstar › 2026 › roster", "entity_type": "OrganicResult" }, { "...": "more results" } ], "TopStory": [ { "entity_type": "TopStory", "url": "https://www.youtube.com/watch?v=0omGCG98tKo" }, { "...": "more results" } ], "Pagination": [ { "current_page": 1, "entity_type": "Pagination", "next_page_url": "https://www.google.com/search?q=NBA+All+Star+2026&start=10", "other_page_urls": { "3": "https://www.google.com/search?q=NBA+All+Star+2026&start=20", "...": "more pages" } } ], "RelatedQuestion": [ { "entity_type": "RelatedQuestion", "question": "Who are the NBA All-Star 2026?" }, { "...": "more questions" } ], "RelatedSearch": [ { "entity_type": "RelatedSearch", "position": "7", "query": "NBA All-Star 2026 tickets", "url": "/search?q=NBA+All-Star+2026+tickets" }, { "...": "more searches" } ] }, "total_entities_count": 32, "entities_count": { "AnswerBox": 1, "InlineImages": 1, "OrganicResult": 8, "Pagination": 1, "RelatedQuestion": 4, "RelatedSearch": 14, "TopStory": 3 }, "metrics": {} }, "nimble_pagination": { "next_page_url": "https://api.us.webit.live/api/v1/realtime/serp?search_engine=google_search&query=NBA+Allstar+2026&country=US&locale=en&parse=true&page_params=...", "other_pages": [ "..." ] }, "nimble_payload": { "next_page": { "search_engine": "google_search", "query": "NBA Allstar 2026", "country": "US", "locale": "en", "parse": "true", "page_params": "q=NBA+All+Star+2026&start=10&..." } }, "driver": "vx6" } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/serp": { "post": { "summary": "SERP", "tags": [ "SERP" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SerpPayload" } ], "examples": [ { "search_engine": "google_search", "query": "NBA Allstar 2026", "country": "US", "locale": "en" } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SerpResponse" } ], "examples": [ { "url": "https://www.google.com/search?hl=en&gl=us&ie=UTF-8&sourceid=chrome&oq=NBA+Allstar+2026&q=NBA+Allstar+2026", "task_id": "4dd71f38-fc3b-4e70-9443-3e70de568395", "status": "success", "data": { "html": ".....", "parsing": { "entities": { "AnswerBox": [ { "display_link": "", "entity_type": "AnswerBox", "snippet": "NBANBA", "snippet_highlighted": [ "NBANBA" ] } ], "OrganicResult": [ { "cleaned_domain": "nba", "displayed_url": "https://www.nba.com › allstar › 2026 › roster", "entity_type": "OrganicResult", "position": 1, "snippet": "2026 All-Star · Latest · Events. Feb. 13: Ruffles All-Star Celebrity Game · Feb. 13: Castrol Rising Stars · Feb. 13: NBA HBCU Classic · Feb. 14: All-Star ...Read more", "title": "2026 All-Star | Roster", "url": "https://www.nba.com/allstar/2026/roster" }, { "cleaned_domain": "wikipedia", "displayed_url": "https://en.wikipedia.org › wiki › 2026_NBA_All-Star_...", "entity_type": "OrganicResult", "position": 2, "snippet": "The 2026 NBA All-Star Game was a round-robin tournament played on February 15, 2026, the 75th edition. It was hosted by the Los Angeles Clippers at the Intuit ...Read more", "title": "2026 NBA All-Star Game", "url": "https://en.wikipedia.org/wiki/2026_NBA_All-Star_Game" }, { "cleaned_domain": "nba", "displayed_url": "https://nbaevents.nba.com › all-star", "entity_type": "OrganicResult", "position": 3, "snippet": "‍Experience basketball's biggest weekend as NBA All-Star 2026 takes over Los Angeles for its historic 75th celebration — a milestone moment that unites fans ...Read more", "title": "All Star 2026 - NBA Events", "url": "https://nbaevents.nba.com/all-star" }, { "cleaned_domain": "instagram", "displayed_url": "2.3M+ followers", "entity_type": "OrganicResult", "position": 4, "snippet": "The 76th NBA All-Star game will be played on Sunday, Feb. 21, at Mortgage Matchup Center, home of the Suns. ... During 2026 @nbaallstar Weekend, we brought ...Read more", "title": "NBA All-Star (@nbaallstar)", "url": "https://www.instagram.com/nbaallstar/" }, { "cleaned_domain": "nba", "displayed_url": "https://www.nba.com › allstar › 2026 › schedule", "entity_type": "OrganicResult", "position": 5, "snippet": "The 2026 NBA All-Star Game will take place on Sunday, Feb. 15, 2026 in Los Angeles, California at the Intuit Dome, the home of the LA Clippers.Read more", "title": "2026 All-Star | Schedule", "url": "https://www.nba.com/allstar/2026/schedule" }, { "cleaned_domain": "youtube", "displayed_url": "594.1K+ views · 2 months ago", "entity_type": "OrganicResult", "position": 6, "thumbnails": [ "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRzjGEYW3zhWa0jfSlNNBqXxpozKaGRxKaUf9rvNWhKlKh70vISyajAMA&s" ], "title": "The FULL 2026 NBA All-Star Teams Introductions", "url": "https://www.youtube.com/watch?v=W9X8fErBuhc" }, { "cleaned_domain": "reddit", "displayed_url": "5 comments · 5 hours ago", "entity_type": "OrganicResult", "position": 7, "thumbnails": [ "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcS9eajrHkAxVTtngwo_k0f73eAMS74WAXHy74NwvZcxZ0aQUiwcArGhyg&s" ], "title": "[Highlights]Three straight All Star connections that stopped the ...", "url": "https://www.reddit.com/r/nba/comments/1t54eg4/highlightsthree_straight_all_star_connections/" }, { "cleaned_domain": "nba", "displayed_url": "https://www.nba.com › allstar › 2026", "entity_type": "OrganicResult", "position": 8, "snippet": "Luka, Giannis lead 2026 All-Star starters. The 10 All-Star starters were revealed on Monday and will participate in the 75th NBA All-Star Game on Feb. 15 in ...Read more", "title": "2026 NBA All-Star", "url": "https://www.nba.com/allstar/2026" }, { "cleaned_domain": "youtube", "displayed_url": "25K+ views · 5 months ago", "entity_type": "OrganicResult", "position": 9, "thumbnails": [ "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTjkVXDwwFS3YDphNtqyNlm1MKghOKiUrdaZSP3Dc1uru1MVq8qW6F6QQ&s" ], "title": "2026 NBA All-Star Game format revealed - NBA Showtime reacts", "url": "https://www.youtube.com/watch?v=7EVGFlnCIR8" } ], "Pagination": [ { "current_page": 1, "entity_type": "Pagination", "next_page_url": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=10&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8NMDegQIMhAW", "other_page_urls": { "3": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=20&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAG", "4": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=30&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAI", "5": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=40&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAK", "6": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=50&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAM", "7": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=60&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAO", "8": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=70&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAQ", "9": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=80&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAS", "10": "https://www.google.com/search?q=NBA+All+Star+2026&sca_esv=d3de13569ac369b6&hl=en&gl=us&ei=Jif7adSTGLuvwbkPo5bO2Qc&start=90&sa=N&sstk=Af77f_duOzNfhdIBXxH89EDT8YgwURfp_XRQz6yUUuwVRzuAId3NQrq_Cjx3St0GgjjzK2Cu4YcpCf0Pf6Ha1znM9o3fQp1fuoe3Qg&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ8tMDegQIMhAU" } } ], "RelatedQuestion": [ { "entity_type": "RelatedQuestion", "question": "Where will the 2026 NBA All Stars be held?" }, { "entity_type": "RelatedQuestion", "question": "What NBA player never dunked in a game?" }, { "entity_type": "RelatedQuestion", "question": "Where is the dunk contest in 2026?" }, { "entity_type": "RelatedQuestion", "question": "Where is NBA All-Star 2027 going to be?" } ], "RelatedSearch": [ { "entity_type": "RelatedSearch", "position": "1", "query": "Nba all-star 2026 tickets", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=Nba+all-star+2026+tickets&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAg7EAE" }, { "entity_type": "RelatedSearch", "position": "2", "query": "Nba all star 2026 roster", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=Nba+all+star+2026+roster&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAhKEAE" }, { "entity_type": "RelatedSearch", "position": "3", "query": "Nba all star 2026 schedule", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=Nba+all+star+2026+schedule&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAhHEAE" }, { "entity_type": "RelatedSearch", "position": "4", "query": "Nba all star 2026 tickets", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=Nba+all+star+2026+tickets&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAhJEAE" }, { "entity_type": "RelatedSearch", "position": "5", "query": "NBA All-Star 2026 3-Point Contest", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=NBA+All-Star+2026+3-Point+Contest&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAhGEAE" }, { "entity_type": "RelatedSearch", "position": "6", "query": "NBA All-Star 2026 reserves", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=NBA+All-Star+2026+reserves&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAhIEAE" }, { "entity_type": "RelatedSearch", "position": "7", "query": "NBA All-Star 2026 Dunk contest", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=NBA+All-Star+2026+Dunk+contest&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAhDEAE" }, { "entity_type": "RelatedSearch", "position": "8", "query": "NBA All-Star 2026 Celebrity Game", "url": "/search?sca_esv=d3de13569ac369b6&hl=en&gl=us&q=NBA+All-Star+2026+Celebrity+Game&sa=X&ved=2ahUKEwjUvobRyKSUAxW7VzABHSOLM3sQ1QJ6BAg-EAE" } ] }, "total_entities_count": 23, "entities_count": { "AnswerBox": 1, "OrganicResult": 9, "Pagination": 1, "RelatedQuestion": 4, "RelatedSearch": 8 }, "metrics": {} } }, "metadata": { "query_time": "2026-05-06T11:33:50.730Z", "query_duration": 9701, "response_parameters": { "input_url": "https://www.google.com/search?hl=en&gl=us&ie=UTF-8&sourceid=chrome&oq=NBA+Allstar+2026&q=NBA+Allstar+2026" }, "driver": "vx6" }, "status_code": 200 } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/serp/async": { "post": { "summary": "SERP Async", "description": "Execute SERP Async Endpoint", "tags": [ "SERP" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SerpPayload" }, { "$ref": "#/components/schemas/AsyncOptions" } ], "examples": [ { "search_engine": "google_search", "query": "NBA Allstar 2026", "country": "US", "locale": "en" } ] } } } }, "responses": { "200": { "description": "Async Task Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncResponse" }, "example": { "status": "success", "task": { "id": "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f", "state": "pending", "created_at": "2026-01-24T12:36:24.685Z", "modified_at": "2026-01-24T12:36:24.685Z", "input": {} } } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/serp/batch": { "post": { "summary": "SERP Batch", "description": "Execute SERP Batch Endpoint", "tags": [ "SERP" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SerpBatchPayload" } ], "examples": [ { "inputs": [ { "query": "best coffe near me" }, { "query": "best tea near me" } ], "shared_inputs": { "search_engine": "google_search", "country": "US", "locale": "en-US", "callback_url": "https://example.com/webhook/callback", "storage_type": "s3", "storage_url": "s3://bucket-name/path/to/object", "storage_compress": true, "storage_object_name": "result-2024-01-15.json" } } ] } } } }, "responses": { "200": { "description": "SERP Batch Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" }, "example": { "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "batch_size": 1, "tasks": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "state": "pending", "output_url": "string", "created_at": "2024-01-15T10:30:00Z", "modified_at": "2024-01-15T10:35:00Z", "account_name": "string", "input": null, "batch_id": "4b0a90bf-c951-42e4-95b3-a95a65ba69fc", "status_code": 200, "api_type": "serp" } ] } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v1/domain-knowledge/driver": { "get": { "description": "Resolves the suggested driver for a given URL or agent name. Exactly one of `url` or `agent` must be provided.", "parameters": [ { "description": "Target domain to resolve driver for (e.g. amazon.com).", "in": "query", "name": "url", "schema": { "description": "Target domain to resolve driver for (e.g. amazon.com).", "examples": [ "amazon.com" ], "type": "string" } }, { "description": "Agent name to resolve driver for (e.g. nimble-ecommerce).", "in": "query", "name": "agent", "schema": { "description": "Agent name to resolve driver for (e.g. nimble-ecommerce).", "examples": [ "nimble-ecommerce" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverResolutionResponse" } } }, "description": "Driver resolution result" }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "404": { "description": "Agent Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "failed" ] }, "msg": { "type": "string", "examples": [ "Agent not found" ] } }, "required": [ "status", "msg" ] }, "example": { "status": "failed", "msg": "Agent not found" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Driver", "tags": [ "Domain Knowledge" ] } }, "/v1/jobs": { "get": { "tags": [ "Jobs" ], "summary": "List Jobs", "description": "List Jobs", "operationId": "list_jobs_v1_jobs_get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search by name or display name", "title": "Q" }, "description": "Search by name or display name" }, { "name": "agent_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by agent name", "title": "Agent Name" }, "description": "Filter by agent name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 20, "title": "Per Page" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "Jobs" ], "summary": "Create Job", "description": "Create Job", "operationId": "create_job_v1_jobs_post", "parameters": [ { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/{job_id}": { "get": { "tags": [ "Jobs" ], "summary": "Get Job", "description": "Get Job", "operationId": "get_job_v1_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Jobs" ], "summary": "Update Job", "description": "Update Job", "operationId": "update_job_v1_jobs__job_id__patch", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Jobs" ], "summary": "Delete Job", "description": "Delete Job", "operationId": "delete_job_v1_jobs__job_id__delete", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/{job_id}/runs": { "get": { "tags": [ "Jobs" ], "summary": "List Runs for Job", "description": "List Runs for Job", "operationId": "list_job_runs_v1_jobs__job_id__runs_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status", "title": "Status" }, "description": "Filter by status" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 20, "title": "Per Page" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRunList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "Jobs" ], "summary": "Trigger Run", "description": "Trigger Run", "operationId": "trigger_job_run_v1_jobs__job_id__runs_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRun" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/runs/{run_id}": { "get": { "tags": [ "Jobs" ], "summary": "Get Run", "description": "Get Run", "operationId": "get_run_v1_jobs_runs__run_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRunDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/runs/{run_id}/cancel": { "post": { "tags": [ "Jobs" ], "summary": "Cancel Run", "description": "Cancel Run", "operationId": "cancel_run_v1_jobs_runs__run_id__cancel_post", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRunCancelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/runs/{run_id}/artifacts": { "get": { "tags": [ "Jobs" ], "summary": "List Run Artifacts", "description": "List Run Artifacts", "operationId": "list_run_artifacts_v1_jobs_runs__run_id__artifacts_get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/runs/{run_id}/artifacts/{artifact_id}": { "get": { "tags": [ "Jobs" ], "summary": "Get Run Artifact", "description": "Get Run Artifact", "operationId": "get_run_artifact_v1_jobs_runs__run_id__artifacts__artifact_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/runs/{run_id}/artifacts/{artifact_id}/preview": { "get": { "tags": [ "Jobs" ], "summary": "Preview Run Artifact", "description": "Preview Run Artifact", "operationId": "preview_run_artifact_v1_jobs_runs__run_id__artifacts__artifact_id__preview_get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactPreview" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/jobs/runs/{run_id}/artifacts/{artifact_id}/download-url": { "get": { "tags": [ "Jobs" ], "summary": "Get Run Artifact Download URL", "description": "Get Run Artifact Download URL", "operationId": "get_run_artifact_download_url_v1_jobs_runs__run_id__artifacts__artifact_id__download_url_get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "token", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactDownloadUrl" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "BearerAuth": [] } ] } } }, "components": { "schemas": { "Parser": { "type": "object", "description": "Custom extraction recipe defining what data to extract and how to structure it. Each property represents a field in the output.", "additionalProperties": { "oneOf": [ { "type": "object", "description": "Terminal parser - extract a single value", "properties": { "type": { "type": "string", "enum": [ "terminal" ] }, "selector": { "$ref": "#/components/schemas/ParserSelector" }, "extractor": { "$ref": "#/components/schemas/ParserExtractor" } }, "required": [ "type", "selector", "extractor" ] }, { "type": "object", "description": "Terminal list parser - extract multiple values", "properties": { "type": { "type": "string", "enum": [ "terminal_list" ] }, "selector": { "$ref": "#/components/schemas/ParserSelector" }, "extractor": { "$ref": "#/components/schemas/ParserExtractor" } }, "required": [ "type", "selector", "extractor" ] }, { "type": "object", "description": "Schema parser - extract nested object", "properties": { "type": { "type": "string", "enum": [ "schema" ] }, "selector": { "$ref": "#/components/schemas/ParserSelector" }, "fields": { "$ref": "#/components/schemas/Parser" } }, "required": [ "type", "fields" ] }, { "type": "object", "description": "Schema list parser - extract list of objects", "properties": { "type": { "type": "string", "enum": [ "schema_list" ] }, "selector": { "$ref": "#/components/schemas/ParserSelector" }, "fields": { "$ref": "#/components/schemas/Parser" } }, "required": [ "type", "fields" ] }, { "type": "object", "description": "Or parser - try multiple strategies", "properties": { "type": { "type": "string", "enum": [ "or" ] }, "parsers": { "type": "array", "items": { "$ref": "#/components/schemas/Parser" } } }, "required": [ "type", "parsers" ] }, { "type": "object", "description": "Const parser - return fixed value", "properties": { "type": { "type": "string", "enum": [ "const" ] }, "value": { "description": "Fixed value to return" } }, "required": [ "type", "value" ] } ] } }, "ParserSelector": { "oneOf": [ { "type": "object", "description": "CSS selector", "properties": { "type": { "type": "string", "enum": [ "css" ] }, "css_selector": { "type": "string", "description": "CSS selector string" } }, "required": [ "type", "css_selector" ] }, { "type": "object", "description": "XPath selector", "properties": { "type": { "type": "string", "enum": [ "xpath" ] }, "path": { "type": "string", "description": "XPath expression" } }, "required": [ "type", "path" ] }, { "type": "object", "description": "JSON selector", "properties": { "type": { "type": "string", "enum": [ "json" ] }, "path": { "type": "string", "description": "JSONPath expression" }, "coercion_filter": { "type": "string", "description": "JSONPath filter for multiple objects" } }, "required": [ "type", "path" ] }, { "type": "object", "description": "Sequence of selectors", "properties": { "type": { "type": "string", "enum": [ "sequence" ] }, "sequence": { "type": "array", "items": { "$ref": "#/components/schemas/ParserSelector" } } }, "required": [ "type", "sequence" ] }, { "type": "object", "description": "Root selector", "properties": { "type": { "type": "string", "enum": [ "root" ] } }, "required": [ "type" ] } ] }, "ParserExtractor": { "oneOf": [ { "type": "object", "description": "Extract text content", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "post_processor": { "$ref": "#/components/schemas/PostProcessor" } }, "required": [ "type" ] }, { "type": "object", "description": "Extract attribute value", "properties": { "type": { "type": "string", "enum": [ "attr" ] }, "attr": { "type": "string", "description": "Attribute name (e.g., href, src)" }, "post_processor": { "$ref": "#/components/schemas/PostProcessor" } }, "required": [ "type", "attr" ] }, { "type": "object", "description": "Extract as JSON", "properties": { "type": { "type": "string", "enum": [ "json" ] }, "post_processor": { "$ref": "#/components/schemas/PostProcessor" } }, "required": [ "type" ] }, { "type": "object", "description": "Extract raw HTML", "properties": { "type": { "type": "string", "enum": [ "raw" ] }, "post_processor": { "$ref": "#/components/schemas/PostProcessor" } }, "required": [ "type" ] } ] }, "PostProcessor": { "type": "object", "description": "Transform extracted data", "properties": { "type": { "type": "string", "enum": [ "number", "string", "date", "regex", "trim", "lowercase", "uppercase" ] } }, "required": [ "type" ] }, "CreateAgentGenerationRequest": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "The prompt to use for the agent generation" }, "agent_name": { "type": "string", "title": "Agent Name", "description": "The name of the agent to generate" }, "url": { "type": "string", "title": "Url", "description": "The URL to use for the agent generation", "examples": [ "https://www.amazon.com/s?k=laptop" ] }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/AgentVersionMetadata" }, { "type": "null" } ], "title": "Metadata", "description": "The metadata of the agent version" }, "input_schema": { "additionalProperties": true, "type": "object", "title": "Input Schema", "description": "The input schema for the agent generation", "examples": { "type": "object", "properties": { "category": { "type": "string" } } } }, "output_schema": { "additionalProperties": true, "type": "object", "title": "Output Schema", "description": "The output schema for the agent generation", "examples": { "type": "object", "properties": { "name": { "type": "string" } } } } }, "type": "object", "required": [ "prompt", "url" ], "title": "CreateAgentGenerationRequest" }, "CreateAgentRefinementRequest": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "The prompt to use for the agent refinement" }, "from_agent": { "type": "string", "title": "From Agent", "description": "The name of the agent to refine", "examples": [ "amazon_pdp" ] } }, "type": "object", "required": [ "prompt", "from_agent" ], "title": "CreateAgentRefinementRequest" }, "AgentGenerationResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "The id of the agent generation" }, "status": { "type": "string", "title": "Status", "description": "The status of the agent generation" }, "agent_name": { "type": "string", "title": "Agent Name", "description": "The name of the agent" }, "version_id": { "type": "string", "format": "uuid", "title": "Version Id", "description": "The version id of the agent" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "The summary of the agent generation" }, "error": { "anyOf": [ { "type": "string", "title": "Error", "description": "The error of the agent generation" }, { "type": "null" } ], "title": "Error", "description": "The error of the agent generation" } }, "type": "object", "required": [ "id", "status" ], "title": "AgentGenerationResponse" }, "AgentVersionMetadata": { "properties": { "data_source": { "type": "string", "title": "Data Source", "description": "The data source of the agent", "examples": [ "Amazon" ] }, "description": { "anyOf": [ { "type": "string", "title": "Description", "description": "The description of the agent", "examples": [ "The Amazon Product Detail Page Agent extracts structured data from individual product pages on Amazon. This agent is ideal for tracking competitor pricing, monitoring catalog changes, and powering product intelligence use cases." ] }, { "type": "null" } ], "title": "Description", "description": "The description of the agent" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "The tags of the agent", "examples": [ [ "Ecommerce", "Search" ] ] }, "domain": { "anyOf": [ { "type": "string", "title": "Domain", "description": "The domain of the agent", "examples": [ "www.amazon.com", "www.google.com" ] }, { "type": "null" } ], "title": "Domain", "description": "The domain of the agent" }, "vertical": { "anyOf": [ { "type": "string", "title": "Category", "description": "The category of the agent", "examples": [ "Ecommerce", "Search" ] }, { "type": "null" } ] }, "entity_type": { "anyOf": [ { "type": "string", "title": "Entity Type", "description": "The entity type of the agent", "examples": [ "Product Detail Page (PDP)", "Search Engine Results Page (SERP)" ] }, { "type": "null" } ] } }, "type": "object", "required": [], "title": "AgentVersionMetadata", "description": "The metadata of the agent version" }, "NetworkCaptureFilter": { "type": "object", "description": "Configuration for capturing network requests made by the page", "properties": { "method": { "type": "string", "description": "Filter by HTTP method", "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ] }, "url": { "type": "object", "description": "URL matching configuration", "properties": { "type": { "type": "string", "description": "How to match URLs", "enum": [ "exact", "contains" ] }, "value": { "type": "string", "description": "The URL or URL pattern to match" } }, "required": [ "value" ] }, "resource_type": { "description": "Filter by request type", "type": "array", "items": { "type": "string", "enum": [ "xhr", "fetch", "stylesheet", "script", "document", "image" ] }, "examples": [ "xhr", "fetch" ] }, "validation": { "type": "boolean", "description": "Validate response content" }, "wait_for_requests_count": { "type": "number", "description": "Wait for this many matching requests", "minimum": 0 }, "wait_for_requests_count_timeout": { "type": "number", "description": "How long to wait in seconds", "minimum": 0, "maximum": 300000 } } }, "AgentBatchBody": { "type": "object", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentBatchInputsPayload", "required": [] } }, "shared_inputs": { "allOf": [ { "$ref": "#/components/schemas/AgentAsyncPayload", "required": [ "Agents" ] } ] } }, "required": [ "inputs", "shared_inputs" ], "description": "Request body for executing a batch of agent requests" }, "BatchResponse": { "type": "object", "properties": { "batch_id": { "type": "string", "description": "Unique identifier for the batch." }, "batch_size": { "type": "number", "description": "Number of tasks in the batch." }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "state": { "type": "string", "enum": [ "pending", "success", "error" ], "description": "Current state of the task.", "examples": [ "pending" ] }, "output_url": { "description": "Storage location of the output data.", "type": "string" }, "status_url": { "type": "string", "format": "uri", "description": "URL for checking the task status.", "examples": [ "https://sdk.nimbleway.com/v1/tasks/123e4567-e89b-12d3-a456-426614174000" ] }, "download_url": { "description": "URL for downloading the task results.", "examples": [ "https://sdk.nimbleway.com/v1/tasks/123e4567-e89b-12d3-a456-426614174000/results" ], "type": "string", "format": "uri" }, "error": { "description": "Error message if the task failed.", "examples": [ "Connection timeout" ], "type": "string" }, "error_type": { "description": "Classification of the error type.", "examples": [ "timeout_error" ], "type": "string" }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "input": { "description": "Original input data for the task." }, "_query": {}, "batch_id": { "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "api_type": { "type": "string", "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract" ] } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "additionalProperties": false }, "description": "List of created tasks." } }, "additionalProperties": false, "description": "Response when a batch of extract tasks is created successfully." }, "BrowserAction": { "type": "object", "description": "An action to perform in the browser (one of: goto, wait, wait_for_element, click, press, fill, scroll, auto_scroll, screenshot, get_cookies, fetch)", "properties": { "goto": { "description": "Navigate to a URL", "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "timeout": { "type": "number" }, "referer": { "type": "string" }, "wait_until": { "type": "string", "enum": [ "load", "domcontentloaded", "networkidle", "commit" ] } }, "required": [ "url" ] } ] }, "wait": { "description": "Pause for a duration", "oneOf": [ { "type": "string", "examples": [ "2s" ] }, { "type": "object", "properties": { "duration": { "type": "string", "examples": [ "2s" ] }, "required": { "type": "boolean" } }, "required": [ "duration" ] } ] }, "wait_for_element": { "description": "Wait for element(s) to appear", "oneOf": [ { "type": "string", "description": "CSS selector" }, { "type": "array", "items": { "type": "string" }, "description": "Array of CSS selectors" }, { "type": "object", "properties": { "selector": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "timeout": { "type": "number" }, "visible": { "type": "boolean" } }, "required": [ "selector" ] } ] }, "click": { "description": "Click an element or coordinates", "oneOf": [ { "type": "string", "description": "CSS selector" }, { "type": "object", "description": "Click by selector or coordinates", "properties": { "selector": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "relative_to": { "type": "string" }, "timeout": { "type": "string" }, "visible": { "type": "boolean" }, "delay": { "type": "string" }, "scroll": { "type": "boolean" }, "count": { "type": "number" }, "required": { "type": "boolean" } } } ] }, "press": { "description": "Press a keyboard key", "oneOf": [ { "type": "string", "examples": [ "Enter" ] }, { "type": "object", "properties": { "key": { "type": "string", "examples": [ "Enter" ] }, "delay": { "type": "number" } }, "required": [ "key" ] } ] }, "fill": { "type": "object", "description": "Fill an input field with text", "properties": { "selector": { "type": "string", "description": "CSS selector of input element" }, "value": { "type": "string", "description": "Text to fill" }, "mode": { "type": "string", "enum": [ "type", "paste" ] }, "timeout": { "type": "number" }, "typing_interval": { "type": "number", "minimum": 10, "maximum": 1000 }, "click_on_element": { "type": "boolean" }, "scroll": { "type": "boolean" }, "visible": { "type": "boolean" }, "delay": { "type": "number" }, "required": { "type": "boolean" } }, "required": [ "selector", "value" ] }, "scroll": { "description": "Scroll the page", "oneOf": [ { "type": "number", "description": "Pixels to scroll (positive = down, negative = up)" }, { "type": "string", "description": "Scroll to bottom or CSS selector" }, { "type": "object", "properties": { "y": { "type": "number" }, "x": { "type": "number" }, "to": { "type": "string", "description": "CSS selector to scroll to" }, "container": { "type": "string", "description": "CSS selector of container" }, "visible": { "type": "boolean" }, "required": { "type": "boolean" } } } ] }, "auto_scroll": { "description": "Automatically scroll to load dynamic content", "oneOf": [ { "type": "boolean" }, { "type": "number", "description": "Max duration in milliseconds" }, { "type": "object", "properties": { "max_duration": { "type": "number" }, "delay_after_scroll": { "type": "number" }, "step_size": { "type": "number", "description": "Pixels to scroll per step" }, "click_selector": { "type": "string", "description": "CSS selector to click before scrolling" }, "container": { "type": "string", "description": "CSS selector of container" }, "idle_timeout": { "type": "number" }, "pause_on_selector": { "type": "string" }, "required": { "type": "boolean" } } } ] }, "screenshot": { "description": "Capture a screenshot", "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "full_page": { "type": "boolean" }, "format": { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "quality": { "type": "number", "minimum": 0, "maximum": 100 } } } ] }, "get_cookies": { "description": "Retrieve cookies", "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain filter for cookies" } } } ] }, "fetch": { "description": "Make HTTP request from browser context", "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "string", "description": "Request body" }, "timeout": { "type": "number" } }, "required": [ "url" ] } ] } } }, "TaskListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "state": { "type": "string", "enum": [ "pending", "success", "error" ], "description": "Current state of the task.", "examples": [ "pending" ] }, "output_url": { "description": "Storage location of the output data.", "type": "string" }, "status_url": { "type": "string", "format": "uri", "description": "URL for checking the task status.", "examples": [ "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ] }, "download_url": { "description": "URL for downloading the task results.", "examples": [ "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ], "type": "string", "format": "uri" }, "error": { "description": "Error message if the task failed.", "examples": [ "Connection timeout" ], "type": "string" }, "error_type": { "description": "Classification of the error type.", "examples": [ "timeout_error" ], "type": "string" }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "input": { "description": "Original input data for the task." }, "_query": {}, "batch_id": { "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "api_type": { "type": "string", "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract" ] } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "additionalProperties": false }, "description": "Array of task objects." }, "pagination": { "type": "object", "properties": { "has_next": { "type": "boolean", "description": "Whether there are more tasks available." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to use for fetching the next page." }, "total": { "type": "number", "description": "Total number of tasks." } }, "required": [ "has_next", "next_cursor", "total" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false, "description": "Paginated list of tasks response." }, "BatchGetResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "id": { "type": "string", "description": "Unique identifier for the batch." }, "completed": { "type": "boolean", "description": "Whether all tasks in the batch have finished." }, "completed_count": { "type": "number", "description": "Number of tasks that have completed so far." }, "progress": { "type": "number", "description": "Completion ratio between 0 and 1." }, "created_at": { "type": "string", "description": "ISO timestamp when the batch was created." }, "completed_at": { "description": "ISO timestamp when the batch completed.", "type": "string" }, "tasks": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "state": { "type": "string", "enum": [ "pending", "success", "error" ], "description": "Current state of the task.", "examples": [ "pending" ] }, "output_url": { "description": "Storage location of the output data.", "type": "string" }, "status_url": { "type": "string", "format": "uri", "description": "URL for checking the task status.", "examples": [ "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ] }, "download_url": { "description": "URL for downloading the task results.", "examples": [ "https://sdk.nimbleway.com/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ], "type": "string", "format": "uri" }, "error": { "description": "Error message if the task failed.", "examples": [ "Connection timeout" ], "type": "string" }, "error_type": { "description": "Classification of the error type.", "examples": [ "timeout_error" ], "type": "string" }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "input": { "description": "Original input data for the task." }, "_query": {}, "batch_id": { "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "api_type": { "type": "string", "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract" ] } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "additionalProperties": false }, { "type": "null" } ] }, "description": "List of tasks in the batch." } }, "required": [ "status", "id", "completed", "completed_count", "progress", "created_at", "tasks" ], "additionalProperties": false, "description": "Response containing batch details with all tasks." }, "BatchProgressResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "id": { "type": "string", "description": "Unique identifier for the batch." }, "completed": { "type": "boolean", "description": "Whether all tasks in the batch have finished." }, "completed_count": { "type": "number", "description": "Number of tasks that have completed so far." }, "completed_at": { "description": "ISO timestamp when the batch completed.", "type": "string" }, "progress": { "type": "number", "description": "Completion ratio between 0 and 1." } }, "required": [ "status", "id", "completed", "completed_count", "progress" ], "additionalProperties": false, "description": "Lightweight batch progress without task details." }, "BatchListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the batch." }, "account_name": { "type": "string", "description": "Name of the account that owns the batch." }, "completed": { "type": "boolean", "description": "Whether all tasks in the batch have finished." }, "created_at": { "type": "string", "description": "ISO timestamp when the batch was created." }, "tasks": { "type": "array", "items": { "type": "string", "description": "Unique identifier for the task." } } }, "required": [ "id", "account_name", "completed", "created_at", "tasks" ] }, "description": "List of batches." }, "pagination": { "type": "object", "properties": { "has_next": { "type": "boolean", "description": "Whether there are more batches available." }, "next_cursor": { "type": "string", "description": "Cursor to use for fetching the next page." }, "total": { "type": "number", "description": "Total number of batches." } }, "required": [ "has_next", "next_cursor", "total" ] } }, "required": [ "data", "pagination" ], "additionalProperties": false, "description": "List of batches." }, "ExtractPayload": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Target URL to scrape", "examples": [ "https://example.com/page" ] }, "country": { "description": "Country used to access the target URL, use ISO Alpha-2 Codes", "examples": [ "US" ], "type": "string" }, "state": { "description": "State used to access the target URL (US and CA only), use ISO Alpha-2 Codes", "examples": [ "NY" ], "type": "string" }, "city": { "description": "City used to access the target URL", "examples": [ "new_york" ], "type": "string" }, "locale": { "description": "LCID standard locale used for the URL request. Alternatively, user can use 'auto' for automatic locale based on geo-location", "examples": [ "en-US" ], "type": "string" }, "render": { "description": "Whether to render JavaScript content using a browser. Use 'auto' to let Nimble automatically select the optimal driver configuration per target domain.", "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "auto" ] } ], "examples": [ true, "auto" ] }, "parse": { "description": "Whether to parse the response content", "type": "boolean" }, "parser": { "$ref": "#/components/schemas/Parser" }, "formats": { "description": "Response format", "examples": [ [ "html", "markdown" ] ], "type": "array", "items": { "type": "string", "enum": [ "html", "markdown", "screenshot", "headers", "links" ] } }, "driver": { "type": "string", "enum": [ "vx6", "vx8", "vx8-pro", "vx10", "vx10-pro", "auto" ], "examples": [ "vx8" ], "title": "Driver", "description": "Browserless drivers available for web extraction. Use 'auto' to let Nimble automatically select the optimal driver per target domain (equivalent to render: 'auto')." }, "auto_driver_configuration": { "type": "object", "description": "Customize automatic driver selection: maps driver configuration names to the number of attempts (0-10) to spend on each before escalating to the next (0 skips it). Key order defines the escalation order; at least one configuration must have attempts > 0. Providing it opts the request into 'auto' driver selection. Ignored when a specific driver is set.", "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 10 }, "propertyNames": { "enum": [ "vx6-fast", "vx6-stealth", "vx8", "vx8-pro", "vx10", "vx10-pro" ] }, "examples": [ { "vx6-fast": 1, "vx8": 3, "vx10-pro": 2 } ] }, "network_capture": { "description": "Intercept and capture network requests made by the page", "type": "array", "items": { "$ref": "#/components/schemas/NetworkCaptureFilter" } }, "browser_actions": { "description": "Array of actions to perform sequentially during browser rendering", "examples": [ { "wait": "2s" }, { "click": { "selector": "#load-more", "timeout": "5s" } } ], "type": "array", "items": { "$ref": "#/components/schemas/BrowserAction" } }, "browser": { "anyOf": [ { "type": "string", "enum": [ "chrome", "firefox" ], "description": "Browser type to emulate", "examples": [ "chrome" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chrome", "firefox" ] }, "version": { "description": "Specific browser version to emulate", "examples": [ "144.0.0" ], "type": "string" } }, "required": [ "name" ] } ] }, "os": { "description": "Operating system to emulate", "examples": [ "windows" ], "type": "string", "enum": [ "windows", "mac os", "linux", "android", "ios" ] }, "no_userbrowser": { "description": "Whether to disable browser-based rendering", "examples": [ false ], "type": "boolean" }, "device": { "description": "Device type for browser emulation", "examples": [ "desktop" ], "type": "string", "enum": [ "desktop", "mobile", "tablet" ] }, "tag": { "description": "User-defined tag for request identification", "examples": [ "campaign-2024-q1" ], "type": "string" }, "is_xhr": { "description": "Whether to emulate XMLHttpRequest behavior", "examples": [ true ], "type": "boolean" }, "http2": { "description": "Whether to use HTTP/2 protocol", "examples": [ true ], "type": "boolean" }, "expected_status_codes": { "description": "Expected HTTP status codes for successful requests", "examples": [ 200, 201 ], "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "referrer_type": { "description": "Referrer policy for the request", "examples": [ "no-referrer" ], "anyOf": [ { "type": "string", "enum": [ "random", "no-referer", "same-origin" ] }, { "type": "string", "enum": [ "google", "bing", "facebook", "twitter", "instagram" ] } ] }, "method": { "description": "HTTP method for the request", "examples": [ "GET" ], "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "render_options": { "type": "object", "properties": { "render_type": { "description": "Type of render completion to wait for", "examples": [ "idle2" ], "type": "string", "enum": [ "domready", "load", "idle0", "idle2" ] }, "headless": { "description": "Whether to run browser in headless mode", "examples": [ true ], "type": "boolean" }, "timeout": { "description": "Maximum time in milliseconds to wait for page render", "examples": [ 30000 ], "type": "number", "minimum": 1 }, "userbrowser": { "description": "Whether to use a persistent browser session", "examples": [ true ], "type": "boolean" }, "include_iframes": { "description": "Whether to include iframe content in the result", "examples": [ true ], "type": "boolean" }, "disabled_resources": { "description": "Types of resources to block from loading", "examples": [ "image", "stylesheet" ], "type": "array", "items": { "type": "string", "enum": [ "other", "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "prefetch", "preflight", "fedcm" ] } }, "adblock": { "description": "Whether to enable ad blocking", "examples": [ true ], "type": "boolean" }, "blocked_domains": { "description": "Domains to block from loading", "examples": [ "ads.example.com", "tracker.com" ], "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "with_performance_metrics": { "description": "Whether to collect performance metrics during rendering", "examples": [ true ], "type": "boolean" }, "no_accept_encoding": { "description": "Disable content encoding to avoid cached responses", "examples": [ true ], "type": "boolean" } } } }, "description": "Request body model for the /extract endpoint", "required": [ "url" ] }, "AgentPayload": { "type": "object", "title": "AgentPayload", "properties": { "agent": { "type": "string", "description": "The agent's name to execute", "examples": [ "google_search" ] }, "params": { "type": "object", "description": "The agent's input parameters, for example query, prodcut_id, etc. Depands on the agent used.", "allOf": [ { "$ref": "#/components/schemas/AgentParams" } ], "examples": [ { "params": { "keyword": "iphone 17", "zip_code": "90210" } } ], "required": [] }, "localization": { "description": "Controls if localization sould be enabled (default false). Some agent support localization based on zip_code or store_id on the site it self. Relevant only when agent is supporting localization", "type": "boolean" }, "formats": { "type": "array", "description": "Output formats to include in the response alongside `data.parsing`. By default, only structured parsed data is returned.", "items": { "type": "string", "enum": [ "html", "markdown", "headers", "links" ] } } }, "required": [ "agent", "params" ], "description": "Request body model for the /agent/run endpoint" }, "AgentBatchInputsPayload": { "type": "object", "title": "AgentBatchInputsPayload", "properties": { "params": { "type": "object", "description": "The agent's input parameters, for example query, prodcut_id, etc. Depands on the agent used.", "allOf": [ { "$ref": "#/components/schemas/AgentParams" } ], "examples": [ { "params": { "keyword": "iphone 17", "zip_code": "90210" } } ], "required": [] }, "localization": { "description": "Controls if localization sould be enabled (default false). Some agent support localization based on zip_code or store_id on the site it self. Relevant only when agent is supporting localization", "type": "boolean" }, "formats": { "type": "array", "description": "Output formats to include in the response alongside `data.parsing`. By default, only structured parsed data is returned.", "items": { "type": "string", "enum": [ "html", "markdown", "headers", "links" ] } } }, "required": [ "agent", "params" ], "description": "Request body model for the /agent/run endpoint" }, "AgentAsyncPayload": { "type": "object", "title": "AgentPayload", "properties": { "agent": { "type": "string", "description": "The agent's name to execute", "examples": [ "google_search" ] }, "params": { "type": "object", "description": "The agent's input parameters, for example query, prodcut_id, etc. Depands on the agent used.", "allOf": [ { "$ref": "#/components/schemas/AgentParams" }, { "$ref": "#/components/schemas/AsyncOptions" } ], "examples": [ { "params": { "keyword": "iphone 17", "zip_code": "90210" } } ], "required": [] }, "localization": { "description": "Controls if localization sould be enabled (default false). Some agent support localization based on zip_code or store_id on the site it self. Relevant only when agent is supporting localization", "type": "boolean" }, "formats": { "type": "array", "description": "Output formats to include in the response alongside `data.parsing`. By default, only structured parsed data is returned.", "items": { "type": "string", "enum": [ "html", "markdown", "headers", "links" ] } } }, "required": [ "agent", "params" ], "description": "Request body model for the /agent/run endpoint" }, "AgentParams": { "type": "object", "minProperties": 1, "description": "Agent input parameters. At least one agent-specific key-value pair is required (e.g., `keyword`, `product_id`). Refer to the specific agent's documentation.", "additionalProperties": true, "properties": { "country": { "type": "string", "description": "Country used to access the target URL, use ISO Alpha-2 Codes", "examples": [ "US" ] }, "locale": { "type": "string", "description": "Language preference for the search results. Use LCID standard", "examples": [ "en" ] }, "tag": { "type": "string", "description": "User-defined tag for request identification", "examples": [ "campaign-2024-q1" ] }, "parse": { "type": "boolean", "description": "Whether to parse the response content", "examples": [ true ] } } }, "SerpPayload": { "type": "object", "title": "SerpPayload", "properties": { "search_engine": { "type": "string", "description": "The search engine to query", "examples": [ "google_search" ], "enum": [ "google_search", "google_aio", "google_maps_search", "google_maps_reviews", "google_maps_place", "google_news", "google_images", "bing_search", "yandex_search" ] }, "query": { "type": "string", "description": "The search query string. Required for google_search, google_news, google_images, and google_maps_search", "examples": [ "NBA Allstars 2026" ] }, "place_id": { "type": "string", "description": "Google Maps place identifier. Required for google_maps_place and google_maps_reviews", "examples": [ "ChIJtRq8oUjLw4kR_tN2GQKUOXs" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "description": "Google Maps place identifier. Required for google_maps_place and google_maps_reviews", "examples": [ "40.7123695" ] }, "longitude": { "type": "string", "examples": [ "-74.0357317" ] } }, "examples": [ { "latitude": "40.7123695", "longitude": "-74.0357317" } ] }, "time": { "type": "string", "description": "Filter results by time range. Only supported for google_search, google_news, and google_images", "examples": [ "hour", "day", "week", "month", "year" ] }, "country": { "type": "string", "default": "US", "description": "Run the search as if from a specific country. Returns geo-localized results (optimized for US)", "examples": [ "US" ] }, "locale": { "type": "string", "description": "Language preference for the search results. Use LCID standard", "examples": [ "en" ] }, "location": { "type": "string", "description": "Location context for the search. Accepted for google_search, google_news, and google_images — not supported for Maps engines. Pass a location string (e.g. \"United States\", \"New York, NY\") or a raw Google UULE value.", "examples": [ "United States", "New York, NY" ] }, "no_html": { "type": "boolean", "default": false, "description": "When set to true, removes the html_content field from the response", "examples": [ true ] }, "num_results": { "description": "Number of results to return (1–100).", "examples": [ 10 ], "maximum": 100, "minimum": 1, "type": "integer" }, "start": { "description": "Result offset for fetching beyond the first batch.", "examples": [ 10 ], "type": "integer" }, "include_pages_html": { "type": "boolean", "default": false, "description": "When set to true, returns raw HTML per individual result page instead of a single stitched HTML string.", "examples": [ true ] }, "device": { "type": "string", "description": "Emulate a specific device type.", "examples": [ "mobile" ], "enum": [ "mobile" ] }, "ads_optimization": { "type": "boolean", "default": false, "description": "When set to true, boosts sponsored results using incognito rendering (requires JS).", "examples": [ true ] } }, "required": [ "search_engine" ], "description": "Request body model for the fast serp endpoint" }, "FastSerpPayload": { "type": "object", "title": "FastSerpPayload", "properties": { "search_engine": { "type": "string", "description": "The search engine to query", "examples": [ "google_search" ], "enum": [ "google_search", "google_news", "google_images", "google_maps_search", "google_maps_place", "google_maps_reviews" ] }, "query": { "type": "string", "description": "The search query string. Required for google_search, google_news, google_images, and google_maps_search", "examples": [ "NBA Allstars 2026" ] }, "place_id": { "type": "string", "description": "Google Maps place identifier. Required for google_maps_place and google_maps_reviews", "examples": [ "ChIJtRq8oUjLw4kR_tN2GQKUOXs" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "description": "Google Maps place identifier. Required for google_maps_place and google_maps_reviews", "examples": [ "40.7123695" ] }, "longitude": { "type": "string", "examples": [ "-74.0357317" ] } }, "examples": [ { "latitude": "40.7123695", "longitude": "-74.0357317" } ] }, "time": { "type": "string", "description": "Filter results by time range. Only supported for google_search, google_news, and google_images", "examples": [ "hour", "day", "week", "month", "year" ] }, "country": { "type": "string", "default": "US", "description": "Run the search as if from a specific country. Returns geo-localized results (optimized for US)", "examples": [ "US" ] }, "locale": { "type": "string", "description": "Language preference for the search results. Use LCID standard", "examples": [ "en" ] }, "location": { "type": "string", "description": "Location context for the search. Accepted for google_search, google_news, and google_images — not supported for Maps engines. Pass a location string (e.g. \"United States\", \"New York, NY\") or a raw Google UULE value.", "examples": [ "United States", "New York, NY" ] }, "no_html": { "type": "boolean", "default": false, "description": "When set to true, removes the html_content field from the response", "examples": [ true ] } }, "required": [ "search_engine" ], "description": "Request body model for the fast serp endpoint" }, "SerpResponse": { "type": "object", "title": "SerpResponse", "description": "Response from the Fast SERP realtime API. All engines share the same top-level envelope; entity types under parsing.entities vary by search_engine.", "properties": { "task_id": { "type": "string", "description": "Unique identifier for this request", "examples": [ "bd46cd9c-50f7-4736-9c4a-660a32e4dc87" ] }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Request status", "examples": [ "success" ] }, "query_time": { "type": "string", "format": "date-time", "description": "ISO timestamp of when the query ran", "examples": [ "2026-03-05T13:47:16.435Z" ] }, "status_code": { "type": "integer", "description": "HTTP status code from the upstream source", "examples": [ 200 ] }, "url": { "type": "string", "description": "The upstream URL that was queried", "examples": [ "https://www.google.com/search?hl=en&gl=us&q=NBA+Allstar+2026" ] }, "input_url": { "type": "string", "description": "The original input URL before any redirects", "examples": [ "https://www.google.com/search?hl=en&gl=us&q=NBA+Allstar+2026" ] }, "html_content": { "type": "string", "nullable": true, "description": "Raw HTML of the response page. Omitted when no_html is true.", "examples": [ "..." ] }, "driver": { "type": "string", "description": "Internal routing driver used for this request", "examples": [ "vx6" ] }, "parsing": { "type": "object", "description": "Structured parsing output. Entity types under entities vary by search_engine." }, "nimble_links": { "type": "object", "nullable": true, "description": "Pagination links as ready-to-use Nimble API URLs (Maps engines)", "properties": { "next_page": { "type": "string", "description": "URL to fetch the next page of results" } } }, "nimble_payload": { "type": "object", "nullable": true, "description": "Next-page parameters as a structured object (web search engines)" } }, "required": [ "task_id", "status", "status_code", "parsing" ] }, "SearchPayload": { "properties": { "query": { "type": "string", "minLength": 1, "title": "Query", "description": "Search query string" }, "locale": { "description": "Language/locale code (e.g., 'en', 'fr', 'de')", "examples": [ "en-US" ], "type": "string", "default": "en" }, "country": { "description": "Country code for geo-targeted results (e.g., 'US', 'GB', 'IL')", "examples": [ "US" ], "type": "string", "default": "US" }, "output_format": { "type": "string", "enum": [ "plain_text", "markdown", "simplified_html" ], "title": "ParsingType", "description": "Output format: plain_text, markdown, or simplified_html", "default": "markdown" }, "max_results": { "type": "integer", "maximum": 100, "minimum": 1, "default": 3, "title": "Num Results", "description": "Maximum number of results to return. Actual count may be lower depending on availability" }, "focus": { "oneOf": [ { "type": "string", "enum": [ "general", "news", "location", "coding", "geo", "shopping", "social", "academic" ], "title": "Search Focus", "description": "Search focus mode (e.g., '`general`', '`news`', '`shopping`')" }, { "type": "array", "maxItems": 10, "items": { "type": "string" }, "description": "List of explicit subagent names (e.g., ['`amazon_serp`', '`target_serp`'])" } ] }, "content_type": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 50, "nullable": true } ], "description": "Filter by content type (only supported with focus=general). Supports semantic groups ('documents', 'spreadsheets', 'presentations') and specific formats ('pdf', 'docx', 'xlsx', etc.)" }, "search_depth": { "type": "string", "enum": [ "lite", "fast", "deep" ], "default": "lite", "title": "Search Depth", "description": "Controls content richness and latency. `lite` = metadata only (title, snippet, URL), `fast` = rich content (~2K chars), `deep` = full page scraping" }, "exclude_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 50, "nullable": true } ], "title": "Exclude Domains", "description": "List of domains to exclude from search results. Maximum 50 domains" }, "include_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 50, "nullable": true } ], "title": "Include Domains", "description": "List of domains to include in search results. Maximum 50 domains" }, "start_date": { "anyOf": [ { "type": "string", "nullable": true } ], "title": "Start Date", "description": "Filter results after this date (format: YYYY-MM-DD or YYYY)" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date", "description": "Filter results before this date (format: YYYY-MM-DD or YYYY)" }, "time_range": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ], "title": "TimeRange", "description": "Filter by recency: hour, day, week, month, or year. Cannot be combined with start_date/end_date" }, "max_subagents": { "type": "integer", "maximum": 10, "minimum": 1, "default": 3, "title": "Max Subagents", "description": "Maximum number of subagents to execute in parallel for WSA focus modes (shopping, social, geo). Ignored for SERP focus modes" } }, "type": "object", "required": [ "query" ], "title": "SearchPayload", "description": "Request body model for the /search endpoint" }, "CrawlPayload": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Url to crawl", "examples": [ "https://example.com" ] }, "name": { "type": "string", "description": "Name of the crawl", "examples": [ "my-crawler-1" ] }, "sitemap": { "description": "Sitemap and other methods will be used together to find URLs", "examples": [ "include" ], "type": "string", "enum": [ "skip", "include", "only" ] }, "crawl_entire_domain": { "description": "Allows the crawler to follow internal links to sibling or parent URLs, not just child paths", "examples": [ false ], "type": "boolean" }, "limit": { "description": "Maximum number of pages to crawl", "examples": [ 100 ], "type": "integer", "minimum": 1, "maximum": 10000 }, "max_discovery_depth": { "description": "Maximum depth to crawl based on discovery order", "examples": [ 3 ], "type": "integer", "minimum": 1, "maximum": 20 }, "exclude_paths": { "description": "URL pathname regex patterns that exclude matching URLs from the crawl", "examples": [ [ "/exclude-this-path", "/and-this-path" ] ], "type": "array", "items": { "type": "string" } }, "include_paths": { "description": "URL pathname regex patterns that include matching URLs in the crawl", "examples": [ [ "/include-this-path", "/and-this-path" ] ], "type": "array", "items": { "type": "string" } }, "ignore_query_parameters": { "description": "Do not re-scrape the same path with different (or none) query parameters", "examples": [ false ], "type": "boolean" }, "allow_external_links": { "description": "Allows the crawler to follow links to external websites", "examples": [ false ], "type": "boolean" }, "allow_subdomains": { "description": "Allows the crawler to follow links to subdomains of the main domain", "examples": [ false ], "type": "boolean" }, "callback": { "description": "Webhook configuration for receiving crawl results", "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook URL to receive crawl results", "examples": [ "https://example.com/webhook" ] }, "headers": { "description": "Headers to send to the webhook URL", "type": "object" }, "metadata": { "description": "Custom metadata that will be included in all webhook payloads for this crawl", "type": "object" }, "events": { "description": "Type of events that should be sent to the webhook URL. (default: all)", "type": "array", "items": { "type": "string", "enum": [ "completed", "page", "failed", "started" ] } } }, "required": [ "url" ] }, { "type": "string", "format": "uri" } ] }, "extract_options": { "$ref": "#/components/schemas/ExtractPayload" } }, "required": [ "url" ] }, "MapPayload": { "properties": { "url": { "type": "string", "format": "uri", "description": "Url to map", "examples": [ "https://example.com" ] }, "sitemap": { "description": "Sitemap and other methods will be used together to find URLs", "examples": [ "include" ], "type": "string", "enum": [ "skip", "include", "only" ] }, "country": { "description": "Country used to access the target URL, use ISO Alpha-2 Codes", "examples": [ "US" ], "type": "string" }, "locale": { "description": "LCID standard locale used for the URL request. Alternatively, user can use 'auto' for automatic locale based on geo-location", "examples": [ "en-US" ], "type": "string" }, "domain_filter": { "description": "Includes subdomains of the main domain in the mapping process", "examples": [ "all" ], "type": "string", "enum": [ "domain", "subdomain", "all" ] }, "limit": { "description": "Maximum number of links to return", "type": "integer", "minimum": 1, "maximum": 100000 } }, "type": "object", "required": [ "url" ], "title": "MapPayload", "description": "Request body model for the /map endpoint" }, "MediaPayload": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the media file to download", "example": "https://example.com/image.jpg" }, "country": { "type": "string", "default": "US", "minLength": 2, "maxLength": 2, "description": "Country used to access the target URL, use ISO Alpha-2 Codes", "example": "US" }, "locale": { "type": "string", "description": "LCID standard locale used for the URL request. Alternatively, user can use 'auto' for automatic locale based on geo-location", "example": "en-US" }, "expected_mime_types": { "type": "array", "items": { "type": "string" }, "description": "Allowed MIME types (supports wildcards like image/*)", "example": [ "image/*", "video/mp4" ] } } }, "MediaAsyncOptions": { "type": "object", "required": [ "url" ], "description": "Cloud storage configuration. Only S3 is currently supported.", "properties": { "url": { "type": "string", "description": "Storage path: s3://bucket/path/", "example": "s3://my-bucket/media/" }, "type": { "type": "string", "enum": [ "s3", "gcs", "do" ], "default": "s3", "description": "Storage provider (only s3 supported currently)" }, "object_name": { "type": "string", "description": "Custom filename (without extension)", "example": "my-file" } } }, "ExtractBatchPayload": { "type": "object", "properties": { "inputs": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ExtractPayload" } ] } }, "shared_inputs": { "allOf": [ { "$ref": "#/components/schemas/AsyncOptions" }, { "$ref": "#/components/schemas/ExtractPayload", "required": [] } ] } } }, "SerpBatchPayload": { "type": "object", "properties": { "inputs": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/SerpPayload" } ] } }, "shared_inputs": { "allOf": [ { "$ref": "#/components/schemas/AsyncOptions" }, { "$ref": "#/components/schemas/SerpPayload", "required": [] } ] } } }, "DriverResolutionResponse": { "additionalProperties": false, "properties": { "agent": { "description": "The input agent name (present when agent query param was used)", "type": "string" }, "antibots": { "description": "List of detected antibots for the domain", "examples": [ [ "cloudflare", "datadome" ] ], "items": { "type": "string" }, "type": "array" }, "description": { "description": "Description of the driver", "type": "string" }, "driver": { "description": "Resolved driver name", "examples": [ "vx10-pro" ], "type": "string" }, "need_to_render": { "description": "Whether the page needs to be rendered to be properly resolved.", "type": "boolean" }, "url": { "description": "The input URL (present when url query param was used)", "type": "string" } }, "required": [ "driver", "antibots", "description" ], "type": "object" }, "AsyncOptions": { "type": "object", "properties": { "storage_type": { "type": "string", "description": "Storage type for async results. Use s3 for Amazon S3 and gs for Google Cloud Platform.", "enum": [ "s3", "gs" ], "examples": [ "s3" ] }, "storage_url": { "type": "string", "description": "Repository URL where output will be saved. Format: s3://Your.Bucket.Name/your/object/name/prefix/ - Output will be saved as TASK_ID.json", "examples": [ "s3://Your.Repository.Path/" ] }, "callback_url": { "type": "string", "format": "uri", "description": "A URL to callback once the data is delivered. The API will send a POST request with task details (without the requested data) when the task completes.", "examples": [ "https://your.callback.url/path" ] }, "storage_compress": { "type": "boolean", "description": "When set to true, the response saved to storage_url will be compressed using GZIP format. If false or not set, response will be saved uncompressed.", "examples": [ false ] }, "storage_object_name": { "type": "string", "description": "Custom name for the stored object instead of the default task ID", "examples": [ "my task" ] } } }, "AsyncResponse": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "success" ] }, "task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique task identifier", "examples": [ "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f" ] }, "state": { "type": "string", "description": "Current state of the task", "enum": [ "pending", "processing", "completed", "failed" ], "examples": [ "pending" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Task creation timestamp", "examples": [ "2026-01-24T12:36:24.685Z" ] }, "account_name": { "type": "string", "description": "The user account name", "examples": [ "my-account" ] }, "api_type": { "type": "string", "description": "The api endpoint used", "enum": [ "agent", "extract" ], "examples": [ "extract" ] }, "modified_at": { "type": "string", "format": "date-time", "description": "Task last modification timestamp", "examples": [ "2026-01-24T12:36:24.685Z" ] }, "input": { "type": "object", "description": "Original request input parameters" } }, "required": [ "id", "state", "created_at", "modified_at", "input" ] } }, "required": [ "status", "task" ], "examples": [ { "status": "success", "task": { "id": "8e8cfde8-345b-42b8-b3e2-0c61eb11e00f", "state": "pending", "account_name": "my-account", "api_type": "extract", "created_at": "2026-01-24T12:36:24.685Z", "modified_at": "2026-01-24T12:36:24.685Z", "input": {} } } ] }, "ExtractResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL that was extracted" }, "task_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the extraction task" }, "status": { "type": "string", "description": "Status of the extraction", "enum": [ "success", "failed" ] }, "status_code": { "type": "integer", "description": "HTTP status code from the target website" }, "data": { "type": "object", "description": "Data from the extraction", "properties": { "html": { "type": "string", "description": "Raw HTML content of the page" }, "headers": { "type": "object", "description": "Response headers from the target website" }, "parsing": { "type": "object", "description": "Parsed data when parsing is enabled" }, "markdown": { "type": "string", "description": "Markdown content when markdown conversion is enabled" }, "cookies": { "type": "object", "description": "Cookies when cookie capture is enabled" }, "fetch_request": { "type": "array", "description": "Captured executed fetch requests when enabled", "items": { "type": "object" } }, "network_capture": { "type": "array", "description": "Captured network activity when enabled", "items": { "type": "object" } }, "browser_actions": { "type": "array", "description": "Browser actions results", "items": { "type": "object" } }, "screenshot": { "type": "string", "description": "Base64 encoded screenshot when enabled (requires rendering)" } } }, "metadata": { "type": "object", "description": "Metadata from the extraction", "properties": { "query_time": { "type": "string", "format": "date-time", "description": "Timestamp when the query was executed" }, "input_url": { "type": "string", "format": "uri", "description": "The original input URL" }, "driver": { "type": "string", "description": "Driver used for extraction (depends on target domain and rendering configuration)", "examples": [ "vx8" ] } } }, "warnings": { "type": "array", "description": "List of warnings", "items": { "type": "string" } } }, "required": [ "url", "task_id", "status", "status_code", "data", "metadata" ] }, "AgentResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL that was extracted" }, "task_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the extraction task" }, "status": { "type": "string", "description": "Status of the extraction", "enum": [ "success", "failed" ] }, "status_code": { "type": "integer", "description": "HTTP status code from the target website" }, "data": { "type": "object", "description": "Data from the extraction", "properties": { "html": { "type": "string", "description": "Raw HTML content of the page" }, "headers": { "type": "object", "description": "Response headers from the target website" }, "parsing": { "type": "object", "description": "Parsed data when parsing is enabled" }, "markdown": { "type": "string", "description": "Markdown content when markdown conversion is enabled" }, "cookies": { "type": "object", "description": "Cookies when cookie capture is enabled" }, "fetch_request": { "type": "array", "description": "Captured executed fetch requests when enabled", "items": { "type": "object" } }, "network_capture": { "type": "array", "description": "Captured network activity when enabled", "items": { "type": "object" } }, "browser_actions": { "type": "array", "description": "Browser actions results", "items": { "type": "object" } }, "screenshot": { "type": "string", "description": "Base64 encoded screenshot when enabled (requires rendering)" } } }, "metadata": { "type": "object", "description": "Metadata from the extraction", "properties": { "query_time": { "type": "string", "format": "date-time", "description": "Timestamp when the query was executed" }, "input_url": { "type": "string", "format": "uri", "description": "The original input URL" }, "driver": { "type": "string", "description": "Driver used for extraction (depends on target domain and rendering configuration)", "examples": [ "vx8" ] }, "agent": { "type": "string", "description": "Agent name used for extraction", "examples": [ "amazon_pdp" ] } } }, "warnings": { "type": "array", "description": "List of warnings", "items": { "type": "string" } } }, "required": [ "url", "task_id", "status", "status_code", "data", "metadata" ] }, "SearchResponse": { "properties": { "total_results": { "type": "integer", "title": "Total Results", "description": "Total number of search results returned in this response", "examples": [ 10 ] }, "results": { "items": { "properties": { "title": { "type": "string", "title": "Title", "description": "Page title from the search result", "examples": [ "Top 10 Web Scraping Tools for 2024" ] }, "description": { "type": "string", "title": "Description", "description": "Meta description or snippet preview from the search result", "examples": [ "Comprehensive guide to the best web scraping tools..." ] }, "url": { "type": "string", "title": "Url", "description": "Full URL of the search result page", "examples": [ "https://example.com/article1" ] }, "content": { "type": "string", "title": "Content", "description": "Full extracted page content. Populated only when search_depth='deep'", "examples": [ "Full parsed content from the page..." ] }, "extra_fields": { "anyOf": [ { "type": "object", "nullable": true } ], "title": "Extra Fields", "description": "Additional metadata extracted from the page (e.g., published date, author, tags). Content varies by page structure and availability.", "examples": [ { "published_date": "2024-01-15" } ] } }, "type": "object", "required": [ "title", "description", "url", "content", "metadata" ], "title": "SearchResultModel", "description": "Individual search result containing page information. Each result includes title, description, URL, extracted content (in Deep Search mode), and optional additional metadata in extra_fields." }, "type": "array", "title": "Results", "description": "Array of search results, each containing title, description, URL, content (in Deep Search mode), and optional metadata" }, "request_id": { "type": "string", "title": "Request Id", "description": "Unique identifier for tracking this search request", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] } }, "type": "object", "required": [ "total_results", "results", "request_id" ], "title": "SearchResponse", "description": "Search API response containing search results with titles, descriptions, URLs, and content", "examples": [ { "total_results": 10, "results": [ { "title": "Top 10 Web Scraping Tools for 2024", "description": "Comprehensive guide to the best web scraping tools...", "url": "https://example.com/article1", "content": "Full parsed content from the page...", "metadata": { "published_date": "2024-01-15" } }, { "title": "Web Scraping Tools Comparison", "description": "Compare features, pricing, and performance...", "url": "https://example2.com/comparison", "content": "Full parsed content from the page...", "metadata": {} } ], "request_id": "123e4567-e89b-12d3-a456-426614174000" } ] }, "MapResponse": { "type": "object", "properties": { "task_id": { "type": "string", "description": "Unique identifier for the map task", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "success": { "type": "boolean", "description": "Indicates if the map request was successful", "examples": [ true ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "description": { "type": "string" } }, "required": [ "url" ], "additionalProperties": false }, "description": "Array of mapped links with optional titles and descriptions", "examples": [ { "url": "https://example.com/page1", "title": "Example Page 1", "description": "This is an example description for page 1" }, { "url": "https://example.com/page2" } ] } }, "required": [ "task_id", "success", "links" ], "additionalProperties": false, "description": "Response schema for map requests", "examples": [ { "task_id": "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3", "success": true, "links": [ { "title": "Web Scraping API", "url": "https://www.example.com/page1", "description": "Complete guide to web scraping" }, { "url": "https://www.nimbleway.com/nimble-api/web" }, { "title": "API Documentation", "url": "https://www.example.com/docs" } ] } ] }, "Error402": { "type": "object", "title": "Error402", "properties": { "status": { "type": "string", "example": "failed", "examples": [ "failed" ] }, "msg": { "type": "string", "description": "Error message indicating the payment issue", "example": "trial expired", "enum": [ "no budget", "limit reached", "trial expired", "trial quota finished" ] } }, "required": [ "status", "msg" ], "example": { "status": "failed", "msg": "trial expired" } }, "Error400": { "type": "object", "title": "Error400", "properties": { "status": { "type": "string", "example": "failed", "examples": [ "failed" ] }, "msg": { "type": "string", "description": "Validation error message describing what went wrong", "example": "Invalid request parameters", "examples": [ "Invalid request parameters" ] }, "error": { "type": "string", "description": "The validation error type", "example": "PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR", "examples": [ "PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR" ] }, "details": { "type": "object", "description": "Detailed validation error information", "example": { "schema_validation_errors": [ { "instancePath": "", "schemaPath": "#/required", "keyword": "required", "params": { "missingProperty": "search_engine" }, "message": "must have required property 'search_engine'" } ] } } }, "required": [ "status", "msg" ], "example": { "status": "failed", "msg": "Invalid request parameters", "error": "PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR", "details": { "schema_validation_errors": [ { "instancePath": "", "schemaPath": "#/required", "keyword": "required", "params": { "missingProperty": "search_engine" }, "message": "must have required property 'search_engine'" } ] } } }, "Error429": { "type": "object", "title": "Error429", "properties": { "status": { "type": "string", "example": "failed", "examples": [ "failed" ] }, "msg": { "type": "string", "example": "Rate limit exceeded", "examples": [ "Rate limit exceeded" ] } }, "required": [ "status", "msg" ], "example": { "status": "failed", "msg": "Rate limit exceeded" } }, "Error500": { "type": "object", "title": "Error500", "properties": { "success": { "type": "string", "example": "false", "examples": [ "false" ] }, "task_id": { "type": "string", "example": "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3", "examples": [ "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3" ] }, "message": { "type": "string", "example": "can't download the query response - please try again", "examples": [ "can't download the query response - please try again" ] } }, "required": [ "success", "task_id", "message" ], "example": { "success": "false", "task_id": "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3", "message": "can't download the query response - please try again" } }, "Artifact": { "properties": { "id": { "type": "string", "title": "Id", "description": "Artifact identifier." }, "type": { "type": "string", "title": "Type", "description": "Artifact type." }, "description": { "type": "string", "title": "Description", "description": "Human-readable artifact description." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the artifact was created." } }, "type": "object", "required": [ "id", "type", "description", "created_at" ], "title": "Artifact", "description": "A file produced by a run." }, "ArtifactDownloadUrl": { "properties": { "url": { "type": "string", "title": "Url", "description": "Pre-signed URL to download the artifact." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "When the download URL expires." } }, "type": "object", "required": [ "url", "expires_at" ], "title": "ArtifactDownloadUrl", "description": "A pre-signed URL for downloading an artifact." }, "ArtifactList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Artifact" }, "type": "array", "title": "Items", "description": "Artifacts produced by the run." } }, "type": "object", "required": [ "items" ], "title": "ArtifactList", "description": "Artifacts produced by a run." }, "ArtifactPreview": { "properties": { "columns": { "items": { "type": "string" }, "type": "array", "title": "Columns", "description": "Column names in the preview." }, "row_count": { "type": "integer", "title": "Row Count", "description": "Total number of rows in the artifact." }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Rows", "description": "Sample rows from the artifact." } }, "type": "object", "required": [ "columns", "row_count", "rows" ], "title": "ArtifactPreview", "description": "A tabular preview of an artifact's contents." }, "CreateJobRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Job name." }, "agent_name": { "type": "string", "title": "Agent Name", "description": "Name of the agent to run." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "Human-friendly job name shown in the UI." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Free-text description of the job." }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedule" }, { "type": "null" } ], "description": "Cron schedule controlling automatic runs." }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/JobInputs" }, { "type": "null" } ], "description": "Input data configuration for the job." }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/JobDestination" }, { "type": "null" } ], "description": "Where the job writes its results." } }, "type": "object", "required": [ "name", "agent_name" ], "title": "CreateJobRequest", "description": "Payload to create a new job." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Job": { "properties": { "id": { "type": "string", "pattern": "^job_[1-9][0-9]*$", "title": "Id", "description": "Unique job identifier (job_)." }, "name": { "type": "string", "title": "Name", "description": "Job name." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "Human-friendly job name shown in the UI." }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name", "description": "Name of the agent this job runs." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Free-text description of the job." }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedule" }, { "type": "null" } ], "description": "Cron schedule controlling automatic runs." }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/JobInputs" }, { "type": "null" } ], "description": "Input data configuration for the job." }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/JobDestination" }, { "type": "null" } ], "description": "Where the job writes its results." }, "last_run_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Run At", "description": "Timestamp of the most recent run." }, "last_run_status": { "anyOf": [ { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ] }, { "type": "null" } ], "title": "Last Run Status", "description": "Status of the most recent run." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "When the job was created." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "When the job was last updated." } }, "type": "object", "required": [ "id", "name" ], "title": "Job", "description": "A configured job: an agent plus its schedule, inputs, and destination." }, "JobContext": { "properties": { "id": { "type": "string", "pattern": "^job_[1-9][0-9]*$", "title": "Id", "description": "Unique job identifier (job_)." }, "name": { "type": "string", "title": "Name", "description": "Internal job name." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "Human-friendly job name shown in the UI." }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name", "description": "Name of the agent this job runs." }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedule" }, { "type": "null" } ], "description": "Cron schedule controlling automatic runs." } }, "type": "object", "required": [ "id", "name" ], "title": "JobContext", "description": "Minimal job context embedded in a run detail." }, "JobDestination": { "properties": { "type": { "type": "string", "enum": [ "file", "s3" ], "title": "Type", "description": "Destination kind: a local 'file' or an 's3' bucket." }, "path": { "type": "string", "title": "Path", "description": "Destination path the output is written to." }, "format": { "type": "string", "enum": [ "jsonl", "csv", "parquet" ], "title": "Format", "default": "parquet", "description": "Output file format." } }, "type": "object", "required": [ "type", "path" ], "title": "JobDestination", "description": "Where a job writes its results." }, "JobInputs": { "properties": { "type": { "type": "string", "enum": [ "s3", "inline", "file" ], "title": "Type", "description": "How inputs are supplied: an 's3' bucket, 'inline' records, or an uploaded 'file'." }, "file_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Path", "description": "Path to the input file; must start with 's3' or 'file_'. Used for 's3'/'file' types." }, "data": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Data", "description": "Inline list of input records. Used when type is 'inline'." } }, "type": "object", "required": [ "type" ], "title": "JobInputs", "description": "Configuration for the input data a job processes." }, "JobList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Job" }, "type": "array", "title": "Items", "description": "Jobs on this page." }, "total": { "type": "integer", "title": "Total", "description": "Total number of jobs matching the query." }, "page": { "type": "integer", "title": "Page", "description": "Current page number." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Number of items per page." } }, "type": "object", "required": [ "items", "total", "page", "per_page" ], "title": "JobList", "description": "A page of jobs." }, "JobRun": { "properties": { "id": { "type": "string", "pattern": "^run_[1-9][0-9]*$", "title": "Id", "description": "Unique run identifier (run_)." }, "job_id": { "type": "string", "pattern": "^job_[1-9][0-9]*$", "title": "Job Id", "description": "Identifier of the job this run belongs to." }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ], "title": "Status", "description": "Current run status." }, "triggered_by": { "type": "string", "enum": [ "schedule", "manual" ], "title": "Triggered By", "description": "What triggered the run: 'schedule' or 'manual'." }, "input_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Input Count", "description": "Number of input records processed." }, "result_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Result Count", "description": "Number of result records produced." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When the run started executing." }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At", "description": "When the run finished." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the run was created." } }, "type": "object", "required": [ "id", "job_id", "status", "triggered_by", "created_at" ], "title": "JobRun", "description": "A single execution of a job." }, "JobRunCancelResponse": { "properties": { "id": { "type": "string", "pattern": "^run_[1-9][0-9]*$", "title": "Id", "description": "Identifier of the cancelled run." }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ], "title": "Status", "description": "Run status after cancellation." } }, "type": "object", "required": [ "id", "status" ], "title": "JobRunCancelResponse", "description": "Result of cancelling a run." }, "JobRunDetail": { "properties": { "id": { "type": "string", "pattern": "^run_[1-9][0-9]*$", "title": "Id", "description": "Unique run identifier (run_)." }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ], "title": "Status", "description": "Current run status." }, "triggered_by": { "type": "string", "enum": [ "schedule", "manual" ], "title": "Triggered By", "description": "What triggered the run: 'schedule' or 'manual'." }, "job": { "$ref": "#/components/schemas/JobContext", "description": "Context of the job this run belongs to." }, "summary": { "anyOf": [ { "$ref": "#/components/schemas/JobRunSummary" }, { "type": "null" } ], "description": "Aggregate metrics for the run." }, "inputs_sample": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Inputs Sample", "description": "Sample of the run's input records." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/JobRunError" }, { "type": "null" } ], "description": "Error details when the run failed." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At", "description": "When the run started executing." }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At", "description": "When the run finished." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the run was created." } }, "type": "object", "required": [ "id", "status", "triggered_by", "job", "created_at" ], "title": "JobRunDetail", "description": "Full detail for a single run." }, "JobRunError": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Human-readable error message." }, "step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step", "description": "Pipeline step where the error occurred." }, "errors_sample": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Errors Sample", "description": "Sample of individual error records from the run." } }, "type": "object", "title": "JobRunError", "description": "Error details for a failed run." }, "JobRunList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/JobRun" }, "type": "array", "title": "Items", "description": "Runs on this page." }, "total": { "type": "integer", "title": "Total", "description": "Total number of runs matching the query." }, "page": { "type": "integer", "title": "Page", "description": "Current page number." }, "per_page": { "type": "integer", "title": "Per Page", "description": "Number of items per page." } }, "type": "object", "required": [ "items", "total", "page", "per_page" ], "title": "JobRunList", "description": "A page of job runs." }, "JobRunSummary": { "properties": { "input_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Input Count", "description": "Number of input records processed." }, "result_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Result Count", "description": "Number of result records produced." }, "match_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Match Rate", "description": "Fraction of inputs that produced a result (result_count / input_count), from 0.0 to 1.0." } }, "type": "object", "title": "JobRunSummary", "description": "Aggregate metrics for a run." }, "JobSchedule": { "properties": { "cron": { "type": "string", "title": "Cron", "description": "Cron expression defining when the job runs." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the schedule is currently active." } }, "type": "object", "required": [ "cron", "enabled" ], "title": "JobSchedule", "description": "Cron-based schedule controlling when a job runs automatically." }, "UpdateJobRequest": { "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "New display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "New description." }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedule" }, { "type": "null" } ], "description": "New cron schedule." }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/JobInputs" }, { "type": "null" } ], "description": "New input data configuration." }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/JobDestination" }, { "type": "null" } ], "description": "New output destination." } }, "type": "object", "title": "UpdateJobRequest", "description": "Partial update for an existing job; omitted fields are left unchanged." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://sdk.nimbleway.com" } ] }