Create and manage tasks

This guide explains how to create, list, inspect, update, and delete tasks in a way that supports long-lived workflows: scheduled monitors, repeated exports, and evolving definitions as sites or APIs change. The examples emphasize classic tasks (URLs + objective + schema); modular and multi-step shapes use the same endpoints with different bodies—see Action types overview.

Task lifecycle at a glance

Core task fields

Field	Required	Description
`name`	Yes	User-facing label for the task
`urls`	Yes	One or more target URLs
`objective`	Yes	High-level extraction instruction
`output_schema`	Yes	Expected JSON output shape
`execution_type`	Yes	`single` or `scheduled`
`schedule`	For scheduled tasks	Cron string
`proxy_locations`	No	Preferred proxy locations
`template_id` or `template_slug`	No	Template-based starting point

For modular single-action tasks, bodies also include fields such as action_type, input_source, limits, and payload as required by your template. For multi-step tasks, an execution_plan carries steps instead of combining with all of the top-level fields above—validation rules are documented on POST /api/v1/tasks in the API Reference.

Create a task

Use:

POST /api/v1/tasks

Example request:

curl -X POST "$TITAN_API_URL/api/v1/tasks" \
  -H "Authorization: Bearer $TITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product monitor",
    "urls": ["https://example.com/products"],
    "objective": "Extract all product names and prices",
    "output_schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "string" }
      }
    },
    "execution_type": "single"
  }'

List and inspect tasks

Use:

GET /api/v1/tasks
GET /api/v1/tasks/:id

Typical list query options:

Query parameter	Purpose
`limit`	Page size
`offset`	Pagination offset
`status`	Filter by task status
`sort`	Sort by creation or update fields

Update a task

Use:

PUT /api/v1/tasks/:id

Update tasks when you need to change:

The target URLs
The objective
The output schema
The execution mode
The schedule
Template-related configuration

Delete a task

Use:

DELETE /api/v1/tasks/:id

Deletion affects the task definition itself. Historical executions remain a separate concern from the task object.

Task design guidance

Recommendation	Why it helps
Keep one stable task per business workflow	Makes execution history easier to reason about
Keep the output schema stable	Reduces downstream parsing changes
Prefer updating an existing task over cloning many near-identical tasks	Simplifies operations
Use schedules only when the workflow is truly recurring	Keeps ad hoc tasks simpler

Common mistakes

Mistake	Better approach
Creating a new task for every run	Create one task and run it repeatedly
Mixing task definition with runtime-only state	Keep runtime logic in executions
Changing the schema frequently on recurring tasks	Version workflows carefully if the schema changes

Get started

Use cases

Action types

About the platform

Use the platform

Dashboard and operations

Worker guides

Task lifecycle at a glance

Core task fields

Create a task

List and inspect tasks

Update a task

Delete a task

Task design guidance

Common mistakes

Next steps

​Task lifecycle at a glance

​Core task fields

​Create a task

​List and inspect tasks

​Update a task

​Delete a task

​Task design guidance

​Common mistakes

​Next steps

Task lifecycle at a glance

Core task fields

Create a task

List and inspect tasks

Update a task

Delete a task

Task design guidance

Common mistakes

Next steps