Skip to main content
POST
/
runs
Run New Task
curl --request POST \
  --url https://api.webagent.cloud/runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "prompt": "<string>",
  "json_schema": "<string>",
  "model": "gpt-4.1",
  "provider": "openai",
  "webhook_url": "<string>",
  "response_format": "text",
  "auth_context_id": "<string>",
  "initial_url": "<string>",
  "session_timeout": 900,
  "wait_for_completion": false
}
'
{
  "id": "<string>",
  "task_id": "<string>",
  "status": "pending",
  "result": "<unknown>",
  "is_done": true,
  "is_successful": true
}

Authorizations

​
x-api-key
string
header
required

Body

application/json

Request model for creating a new task and task run.

​
prompt
string
required

The task to be performed by the agent

Minimum string length: 3
​
json_schema

The JSON schema for the task result

​
model
string | null
default:gpt-4.1

The model to use for the task. Defaults to 'gpt-4.1'.

​
provider
string | null
default:openai

The provider to use for the task. Defaults to 'openai'.

​
webhook_url
string | null

The webhook URL to send the result to

​
response_format
string | null
default:text

Whether to return the result as text or JSON

​
auth_context_id
string | null

The id of associated auth context

​
initial_url
string | null

The initial URL to navigate to before executing the task

​
session_timeout
integer | null
default:900

The timeout for the task in seconds

​
wait_for_completion
boolean | null
default:false

Whether to wait for the task to complete before returning the response. If false, the task will be executed in the background and the response will contain only the task ID.

Response

Successful Response

Represents a Run.

​
id
string
required

The ID of the created task run

​
task_id
string
required

The ID of the created task

​
status
enum<string>
default:pending

The status of the agent's task

Available options:
success,
failure,
pending
​
result
any | null

The final result of the agent's task

​
is_done
boolean | null

Whether the agent has completed its task

​
is_successful
boolean | null

Whether the agent was successful in completing its task