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

# Run Spell

The Run Spell endpoint lets you call your spell programmatically. We have two modes you can use:

* Wait Mode (`wait: true`): Will keep the connection open until the spell returns. Best for spells that run quickly (\< 60s).
* Polling Mode (`wait: false`): Will return a spell run ID for you to poll for results.

Wait Mode is simpler to implement, and works for most spells. Polling Mode is best for long-running spells, or if your architecture isn't suited for handling long-running connections.

To call a spell, you'll need to enter the spell ID (found in the URL or on the spell page's API tab) and the JSON representation of the inputs (found in the spell page's API tab).

## Wait Mode

To start the spell run:

<CodeGroup>
  ```javascript Javascript
  const response = await fetch('https://api-v2.respell.ai/spells/start', {
    method: 'POST',
    headers: {
      authorization: 'Bearer {{ YOUR API KEY }}',
      accept: 'application/json',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      spellId: '{{ YOUR SPELL ID }}',
      wait: true,
      inputs: {
          "search_topic": "{{ YOUR CUSTOM INPUT }}"
        },
    }),
  })
  ```

  ```python Python
  import requests
  import json

  response = requests.post(
    'https://api-v2.respell.ai/spells/start',
    headers={
      "authorization": "Bearer {{ YOUR API KEY }}",
      "accept": "application/json",
      "content-type": "application/json"
    },
    data=json.dumps({
      "spellId": '{{ YOUR SPELL ID }}',
      "wait": true,
      "inputs": {
          "search_topic": "{{ YOUR CUSTOM INPUT }}"
        }
    }),
  )
  ```

  ```bash Bash
  curl 'https://api-v2.respell.ai/spells/start' \
    --header 'Accept: application/json' \
    --header 'x-api-key: {{ YOUR API KEY }}' \
    --header 'Content-Type: application/json' \
    --data '{
        "spellId": "clxdq2y1w008g2l7by88758uh",
        "wait": "true",
        "inputs": {
          "search_topic": "{{ YOUR CUSTOM INPUT }}"
        }
    }'
  ```
</CodeGroup>

The spell run results will be returned as JSON in the response body:

<CodeGroup>
  ```json JSON
  {
    "outputs": {
      "search_topic": "{{ SPELL RUN OUTPUT }}"
    }
  }
  ```
</CodeGroup>

## Polling Mode

To start the spell run:

<CodeGroup>
  ```javascript Javascript
  const response = await fetch('https://api-v2.respell.ai/spells/start', {
    method: 'POST',
    headers: {
      authorization: 'Bearer {{ YOUR API KEY }}',
      accept: 'application/json',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      spellId: '{{ YOUR SPELL ID }}',
      wait: false,
      inputs: {
          "search_topic": "{{ YOUR CUSTOM INPUT }}"
        },
    }),
  })
  ```

  ```python Python
  import requests
  import json

  response = requests.post(
    'https://api-v2.respell.ai/spells/start',
    headers={
      "Authorization": "Bearer {{ YOUR API KEY }}",
      "Accept": "application/json",
      "Content-Type": "application/json"
    },
    data=json.dumps({
      "spellId": '{{ YOUR SPELL ID }}',
      "wait": false,
      "inputs": {
          "search_topic": "{{ YOUR CUSTOM INPUT }}"
        }
    }),
  )
  ```

  ```bash Bash
  curl 'https://api-v2.respell.ai/spells/start' \
    --header 'Accept: application/json' \
    --header 'x-api-key: {{ YOUR API KEY }}' \
    --header 'Content-Type: application/json' \
    --data '{
        "spellId": "{{ YOUR SPELL ID }}",
        "wait": "false",
        "inputs": {
          "search_topic": "{{ YOUR CUSTOM INPUT }}"
        }
    }'
  ```
</CodeGroup>

The spell run ID will be returned as JSON in the response body:

<CodeGroup>
  ```json
  {
      "runId": {{ SPELL RUN ID }},
  }
  ```
</CodeGroup>

You can use the spell run ID to poll for results:

<CodeGroup>
  ```javascript Javascript
  const response = await fetch('https://api-ox4n3wkxsa-uw.a.run.app/spells/getRun', {
    method: 'GET',
    headers: {
      authorization: 'Bearer {{ YOUR API KEY }}',
      accept: 'application/json',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      runId: {{ SPELL RUN ID }},
    }),
  })
  ```

  ```python Python
  import requests
  import json

  response = requests.get(
    'https://api-ox4n3wkxsa-uw.a.run.app/spells/getRun',
    headers={
      "Authorization": "Bearer {{ YOUR API KEY }}",
      "Accept": "application/json",
      "Content-Type": "application/json"
    },
    data=json.dumps({
      "runId": {{ SPELL RUN ID}},
    }),
  )
  ```

  ```bash Bash
  curl -X GET 'https://api-ox4n3wkxsa-uw.a.run.app/spells/getRun?runId={{ SPELL RUN ID }}' \
    --header 'Accept: application/json' \
    --header 'x-api-key: {{ YOUR API KEY }}' \
    --header 'Content-Type: application/json'
  ```
</CodeGroup>

The spell run results will be returned as JSON in the response body once the run is successful:

<CodeGroup>
  ```json
  // If the run is finished, any outputs will be returned in 'outputs'
  {
    "outputs": {
      "search_topic": "{{ SPELL RUN OUTPUT }}"
    },
    "state": "success" // "success", "failure", "error", or "inProgress"
  }
  // If the run is inProgress, 'outputs' will be an empty object
  {
    "outputs": {},
    "state": "inProgress"
  }
  ```
</CodeGroup>