> ## Documentation Index
> Fetch the complete documentation index at: https://webscraping.titannet.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage tasks

> Create, list, update, and delete tasks—the reusable unit of extraction, monitoring, and modular web intelligence workflows in Titan.

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](/about-platform/action-types/overview).

## Task lifecycle at a glance

```mermaid theme={null}
stateDiagram-v2
    [*] --> active: Create task
    active --> paused: Pause
    paused --> active: Resume
    active --> completed: Complete
    active --> failed: Fail
    active --> deleted: Delete
```

## 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:

```bash theme={null}
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 |

## Next steps

* [Run one-off and scheduled tasks](/use-the-platform/run-one-off-and-scheduled-scrapes)
* [Monitor and control executions](/use-the-platform/monitor-and-control-executions)
* [Example: scheduled monitoring workflow](/examples/example-scheduled-monitoring-workflow)