Action types overview

Titan is built around actions, not only “given these URLs, return fields.” A task can describe discovery (search), link expansion (crawl), structured extraction (scrape), and HTTP tool calls (api_call). You combine them into single-action tasks (one action_type) or multi-action tasks (execution_plan with multiple steps and input_source wiring). You can express discovery, link expansion, structured extraction, and outbound HTTP in one task model on your infrastructure, with templates, scripts, billing, and execution history aligned to the same task and execution IDs.

Tab titles (cURL, Go, TypeScript, Python, Rust) match Authentication and the Quickstart. Rust examples use ureq and serde_json with .expect() for short, copy-friendly snippets.

The four action types

`action_type`	Purpose
`search`	Discover URLs or documents from the open web using queries and ranking before you commit to specific pages.
`crawl`	Follow links from seeds with depth and limits—navigation-first expansion of what to read.
`scrape`	Given concrete URLs, extract structured data (and media where applicable) against an output schema.
`api_call`	Call external HTTP APIs as a first-class step (payloads, validation, and keys are part of your configuration).

Serious workflows often chain two or more actions (for example search → scrape, crawl → scrape, or api_call → scrape).

How tasks express actions

Classic (non-modular) task

You supply urls, objective, output_schema, and optional template or script selection. The platform treats this as a single extraction-style run unless you add modular fields.

Single-action modular task

Set action_type to one of search, crawl, scrape, or api_call, plus modular fields, and omit execution_plan:

input_source — where inputs come from for that step (see table below).
template_id / template_slug and optional script_id / script_version — bind validation, defaults, and runtime script.
limits, payload, retry_policy — step-level behavior.

The service validates configuration, resolves the script, and saves a single-step plan so each execution loads the same definition. Responses expose is_modular when an action is in play; is_multi_action stays false for a single effective step.

Multi-action modular task (`execution_plan`)

Send an execution_plan on create or update with one or more steps. Each step includes step_id, action_type, input_source, optional template or script per step, limits, payload, retry policy, and optional next_step_id / metadata. Rules that matter for the API:

execution_plan cannot be combined with top-level modular fields (action_type, template_id, output_schema, limits, payload, and so on). The plan must be self-contained; the same mutual exclusion applies on PUT /api/v1/tasks/:id when updating with a plan.
Saving multi-step tasks requires your Titan environment to support persisted multi-step workflows. If that is not enabled, creating a task with an execution_plan may fail with a clear error—check with your operator or support for your environment.
secret_payload is rejected on create; pass secrets at run time via POST /api/v1/tasks/:id/run or POST /api/v1/executions payloads.

For modular runs, the stored workflow is the source of truth: execution_plan overrides on trigger are not supported the way they are for some classic tasks.

Input sources (`input_source`)

Value	Meaning
`static_urls`	Use the task’s configured `urls` (after validation for the action). Typical for the first step or whenever inputs should only be user-supplied seeds.
`previous_step`	Consume outputs from the prior step (for example URLs from search feeding scrape).
`task_url_inventory`	Drive work from the task URL inventory for large or evolving URL sets. Not every environment exposes this flow.

Validation rejects inconsistent combinations; POST /api/v1/tasks errors reflect the same rules applied when a run is started.

Templates and scripts

Templates bundle metadata and versioned scripts; script rows can declare an action_type so you know which behavior a version implements. List script versions with GET /api/v1/templates/:id/scripts (include_inactive=true when you need inactive rows). Multi-action plans can point different steps at different templates when your product allows it.

Preview and iteration

POST /api/v1/executions/preview — dry-run an execution_plan (objective + plan) without persisting a permanent task.
POST /api/v1/templates/:id/preview — template-scoped preview (requires executions:write; subject to preview quotas).

Set TITAN_API_URL to your Task Service origin (no /api/v1 suffix) and TITAN_TOKEN to a bearer token with executions:write. Replace the empty steps array with a real plan when you call this for real.

cURL
Go
TypeScript
Python
Rust

curl -sS -X POST "$TITAN_API_URL/api/v1/executions/preview" \
  -H "Authorization: Bearer $TITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Dry-run a modular plan before persisting a task",
    "execution_plan": { "steps": [] }
  }'

body := map[string]any{
  "objective":        "Dry-run a modular plan before persisting a task",
  "execution_plan": map[string]any{"steps": []any{}},
}
b, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", os.Getenv("TITAN_API_URL")+"/api/v1/executions/preview", bytes.NewReader(b))
req.Header.Set("Authorization", "Bearer "+os.Getenv("TITAN_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(string(out))

const base = process.env.TITAN_API_URL!;
const token = process.env.TITAN_TOKEN!;
const res = await fetch(`${base}/api/v1/executions/preview`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    objective: "Dry-run a modular plan before persisting a task",
    execution_plan: { steps: [] },
  }),
});
console.log(await res.text());

import json
import os
import urllib.request

payload = {
    "objective": "Dry-run a modular plan before persisting a task",
    "execution_plan": {"steps": []},
}
req = urllib.request.Request(
    f"{os.environ['TITAN_API_URL']}/api/v1/executions/preview",
    data=json.dumps(payload).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['TITAN_TOKEN']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req) as resp:
    print(resp.read().decode())

use serde_json::json;

let base = std::env::var("TITAN_API_URL").expect("TITAN_API_URL");
let token = std::env::var("TITAN_TOKEN").expect("TITAN_TOKEN");
let body = json!({
    "objective": "Dry-run a modular plan before persisting a task",
    "execution_plan": { "steps": [] }
});
let resp = ureq::post(format!("{base}/api/v1/executions/preview"))
    .set("Authorization", &format!("Bearer {token}"))
    .set("Content-Type", "application/json")
    .send_json(body)
    .expect("preview");
println!("{}", resp.into_string().expect("body"));

Where to read next

Search
Scrape
Crawl
API call
Tasks and Executions for lifecycle vocabulary.
API Reference → Task Service API for OpenAPI-level request and response fields.

Get started

Use cases

Action types

About the platform

Use the platform

The four action types

How tasks express actions

Classic (non-modular) task

Single-action modular task

Multi-action modular task (`execution_plan`)

Input sources (`input_source`)

Templates and scripts

Preview and iteration

Where to read next

Get started

Use cases

Action types

About the platform

Use the platform

Documentation Index

​The four action types

​How tasks express actions

​Classic (non-modular) task

​Single-action modular task

​Multi-action modular task (execution_plan)

​Input sources (input_source)

​Templates and scripts

​Preview and iteration

​Where to read next

The four action types

How tasks express actions

Classic (non-modular) task

Single-action modular task

Multi-action modular task (`execution_plan`)

Input sources (`input_source`)

Templates and scripts

Preview and iteration

Where to read next