Nimbleway Tasks API
The Tasks API from Nimbleway — 6 operation(s) for tasks.
OpenAPI Specification
openapi: 3.1.0
info:
title: Nimble SDK Agents Tasks API
version: 1.0.0
description: The AI-Native SDK for Real-Time Web Data at scale
servers:
- url: https://sdk.nimbleway.com
tags:
- name: Tasks
paths:
/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'
components:
schemas:
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'
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
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.
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
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.
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 e
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nimbleway/refs/heads/main/openapi/nimbleway-tasks-api-openapi.yml