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

# Run a Preset

> Run a saved template or tool request, optionally changing some of its inputs for this run.

Runs a preset and answers the way the job behind it answers.

* A **template preset** starts a template run. The response is the same as [Run a Template](https://docs.spidra.io/api-reference/templates/run.md), with `presetId` added; poll the run with [GET /template-runs/\{runId}](https://docs.spidra.io/api-reference/templates/get-run.md).
* A **tool preset** sends its saved request to the tool. The response is exactly that tool's response, with `presetId` and `tool` added: a map answers with its links straight away, a scrape or crawl with a job ID to poll at its own endpoint.

```bash theme={null}
curl -X POST https://api.spidra.io/api/presets/a044216c-075e-4397-abdc-75d8b2a5593e/runs \
  -H "Authorization: Bearer $SPIDRA_API_KEY"
```

A map preset, shortened to one link:

```json theme={null}
{
  "status": "success",
  "links": [{ "url": "https://docs.python.org/3/library/asyncio.html", "title": "asyncio" }],
  "total": 21,
  "scanned": 595,
  "sources": { "sitemap": 7, "pages": 588 },
  "creditsUsed": 1,
  "durationMs": 8748,
  "presetId": "a044216c-075e-4397-abdc-75d8b2a5593e",
  "tool": "map"
}
```

## Change some inputs for one run

`overrides` replaces template inputs, or request fields of a tool preset, for this run only. The preset itself doesn't change.

```bash theme={null}
curl -X POST https://api.spidra.io/api/presets/a044216c-075e-4397-abdc-75d8b2a5593e/runs \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "overrides": { "search": "typing" } }'
```

That run mapped the same site for `typing` instead of `asyncio`.

Add `"wait": true` to wait for a quick result, as with a template run or a batch scrape.

## Errors

| Status | When |
| - | - |
| `404` | No preset with this ID on your account. |
| `409` | The preset's template no longer exists (`TEMPLATE_RETIRED`). |
| `503` | The preset's template is paused for maintenance (`TEMPLATE_PAUSED`). Nothing was charged. |

Anything else (not enough credits, a bad override) comes back from the tool or template as it would for a direct request.


## OpenAPI

````yaml POST /presets/{presetId}/runs
openapi: 3.1.0
info:
  title: Spidra API
  version: 1.0.0
  description: >-
    Public API endpoints for web scraping via Spidra. Authenticate with
    `Authorization: Bearer YOUR_API_KEY`.
servers:
  - url: https://api.spidra.io/api
security:
  - BearerAuth: []
  - ApiKeyAuth: []
paths:
  /presets/{presetId}/runs:
    post:
      tags:
        - Presets
      summary: Run a Preset
      description: >-
        Runs a preset. A template preset starts a template run and answers like
        [Run a Template](/api-reference/templates/run), with `presetId` added. A
        tool preset sends its saved request to the tool and answers exactly as
        that tool does (a map answers with its links, a scrape with a job ID to
        poll), with `presetId` and `tool` added.
      parameters:
        - name: presetId
          in: path
          required: true
          schema:
            type: string
          description: The preset's ID.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                overrides:
                  type: object
                  description: >-
                    Change some inputs (template presets) or request fields
                    (tool presets) for this run only, such as `{ "search":
                    "typing" }`.
                wait:
                  type: boolean
                  default: false
                  description: Wait for a quick result, where the tool supports it.
            example:
              overrides:
                search: typing
      responses:
        '200':
          description: Finished (a map, or a run that finished within `wait`).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '202':
          description: Started. Poll the run or the tool's job.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No preset with this ID on your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The preset's template no longer exists (`TEMPLATE_RETIRED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            The preset's template is paused (`TEMPLATE_PAUSED`). Nothing was
            charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
      required:
        - status
        - message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.