Skip to main content
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

FieldRequiredDescription
nameYesUser-facing label for the task
urlsYesOne or more target URLs
objectiveYesHigh-level extraction instruction
output_schemaYesExpected JSON output shape
execution_typeYessingle or scheduled
scheduleFor scheduled tasksCron string
proxy_locationsNoPreferred proxy locations
template_id or template_slugNoTemplate-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 parameterPurpose
limitPage size
offsetPagination offset
statusFilter by task status
sortSort 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

RecommendationWhy it helps
Keep one stable task per business workflowMakes execution history easier to reason about
Keep the output schema stableReduces downstream parsing changes
Prefer updating an existing task over cloning many near-identical tasksSimplifies operations
Use schedules only when the workflow is truly recurringKeeps ad hoc tasks simpler

​
Common mistakes

MistakeBetter approach
Creating a new task for every runCreate one task and run it repeatedly
Mixing task definition with runtime-only stateKeep runtime logic in executions
Changing the schema frequently on recurring tasksVersion workflows carefully if the schema changes

​
Next steps