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

# titan_run_template

> Run a curated Titan template by slug when the dedicated search, fetch, and crawl tools do not expose the option you need.

`titan_run_template` is the escape hatch. It runs an allowlisted Titan template directly, giving you access to template-specific `payload` fields and proxy location control that the dedicated tools do not surface.

For most work, prefer [`titan_search`](/docs/mcp/tools/titan-search), [`titan_fetch`](/docs/mcp/tools/titan-fetch), or [`titan_crawl`](/docs/mcp/tools/titan-crawl)—they run the same templates with parameters shaped for agents.

**Required scope:** `mcp:templates:run`

## Parameters

<ParamField body="template_slug" type="string" required>
  Slug of an allowlisted template. Anything outside the allowlist returns `template_not_found`. List valid slugs with [`titan_list_templates`](/docs/mcp/tools/titan-list-templates).
</ParamField>

<ParamField body="urls" type="string[]">
  Target URLs, up to 100. Required for templates that take static URLs, which is all eight current templates.
</ParamField>

<ParamField body="payload" type="object">
  Template-specific options. Valid keys are defined by the template's `input_schema`.
</ParamField>

<ParamField body="max_results" type="integer">
  Convenience shortcut merged into `payload` as `max_results`.
</ParamField>

<ParamField body="proxy_locations" type="string[]">
  Geographic locations to route the run through. Useful when a target serves different content by region.
</ParamField>

<ParamField body="wait_for_completion" type="boolean" default="true">
  Wait for results inside the call.
</ParamField>

<ParamField body="timeout_seconds" type="integer" default="30">
  Seconds to wait, capped at 30.
</ParamField>

<ParamField body="idempotency_key" type="string">
  Deduplicate repeated calls for 24 hours. See [Idempotency and retries](/docs/mcp/idempotency-and-retries).
</ParamField>

## Example

Run the generic page extraction template with options the dedicated fetch tool does not expose:

```json theme={null}
{
  "template_slug": "generic-web-page-extraction-v1",
  "urls": ["https://example.com/pricing"],
  "payload": {
    "format": "markdown",
    "only_main_content": false,
    "include_image_links": false,
    "max_chars_per_url": 20000
  },
  "proxy_locations": ["de"]
}
```

## Response

Records come back as raw template output rather than a tool-specific shape, because the shape is whatever the template's `output_schema` defines.

```json theme={null}
{
  "run_id": "b4f18c27-3e95-4d60-a712-9f5c3e8b1d47",
  "status": "completed",
  "template": {
    "slug": "generic-web-page-extraction-v1",
    "name": "Generic Web Page Extraction",
    "category": "generic",
    "action_type": "scrape",
    "provider": "generic"
  },
  "records": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "status_code": 200,
      "content_format": "markdown",
      "content": "# Pricing\n\n## Starter\n$29/month...",
      "retrieved_at": "2026-07-27T09:44:18Z"
    }
  ],
  "usage": {
    "backend_execution_id": "b4f18c27-3e95-4d60-a712-9f5c3e8b1d47",
    "billing_unit": "successful_delivery",
    "records_returned": 1,
    "credits_estimated": 1,
    "credits_consumed": 1,
    "billing_status": "billable"
  },
  "warnings": [],
  "request_id": "req_9e4b2c7f1a3d8065"
}
```

The `template` object echoes which template ran, so an agent handling several templates can branch on it without tracking state.

## Allowlist enforcement

Only the eight templates in the MCP allowlist are runnable. User-owned, admin, inactive, and experimental templates return:

```json theme={null}
{
  "code": "template_not_found",
  "message": "template \"my-private-template\" is not allowlisted for MCP",
  "retryable": false
}
```

This holds even if the same template is reachable through the Task Service API with your key. The allowlist is enforced at the MCP boundary, not by permission.

## Credits

Credit estimates follow the template's capability:

| Capability | Estimate                            |
| ---------- | ----------------------------------- |
| `search`   | 1 credit per run                    |
| `fetch`    | 1 credit per URL                    |
| `crawl`    | `max_results` when set, otherwise 1 |

Final billing is always based on records actually delivered. See [Credits and usage](/docs/mcp/credits-and-usage).

## When to use this instead of a dedicated tool

| Situation                                                     | Tool                                           |
| ------------------------------------------------------------- | ---------------------------------------------- |
| You need a `payload` field the dedicated tool does not expose | `titan_run_template`                           |
| You need `proxy_locations` to control request geography       | `titan_run_template`                           |
| You want the friendliest parameters and normalized output     | `titan_search` / `titan_fetch` / `titan_crawl` |

## Next steps

* [titan\_list\_templates](/docs/mcp/tools/titan-list-templates) — discover slugs and their schemas
* [titan\_get\_run](/docs/mcp/tools/titan-get-run) — poll runs that outlive the wait window