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

# Bulk Spell Runs

The Bulk Spell Run endpoint is very similar to the standard Run Spell endpoint with some key differences. Mainly, there is no wait mode, as you will always receive bulkRunId as a return value.

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

## Bulk Mode

To start the a bulk spell run:

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

  ```python Python
  import requests
  import json

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

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

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

<CodeGroup>
  ```json JSON
  {
    "runId": "{{ BULK RUN ID }}"
  }
  ```
</CodeGroup>

## Cancel Bulk Run

To cancel the bulk run:

<CodeGroup>
  ```javascript Javascript
  const response = await fetch('https://api-v2.respell.ai/spells/cancelBulk', {
    method: 'POST',
    headers: {
      authorization: 'Bearer {{ YOUR API KEY }}',
      accept: 'application/json',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      groupId: '{{ YOUR BULK RUN ID }}',
    }),
  })
  ```

  ```python Python
  import requests
  import json

  response = requests.post(
    'https://api-v2.respell.ai/spells/cancelBulk',
    headers={
      "Authorization": "Bearer {{ YOUR API KEY }}",
      "Accept": "application/json",
      "Content-Type": "application/json"
    },
    data=json.dumps({
      "groupId": '{{ YOUR SPELL ID }}',
      
    }),
  )
  ```

  ```bash Bash
  curl 'https://api-v2.respell.ai/spells/cancelBulk' \
    --header 'Accept: application/json' \
    --header 'x-api-key: {{ YOUR API KEY }}' \
    --header 'Content-Type: application/json' \
    --data '{
        "groupId": "{{ YOUR SPELL ID }}",
        
    }'
  ```
</CodeGroup>

This will stop all runs immediately.

## Get Bulk Runs

To get the results of a bulk run:

<CodeGroup>
  ```javascript Javascript
  const response = await fetch('https://api-v2.respell.ai/spells/getBulkRuns', {
    method: 'POST',
    headers: {
      authorization: 'Bearer {{ YOUR API KEY }}',
      accept: 'application/json',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      groupId: '{{ YOUR BULK RUN ID }}',
    }),
  })
  ```

  ```python Python
  import requests
  import json

  response = requests.post(
    'https://api-v2.respell.ai/spells/getBulkRuns',
    headers={
      "Authorization": "Bearer {{ YOUR API KEY }}",
      "Accept": "application/json",
      "Content-Type": "application/json"
    },
    data=json.dumps({
      "groupId": '{{ YOUR BULK RUN ID }}',
      
    }),
  )
  ```

  ```bash Bash
  curl 'https://api-v2.respell.ai/spells/getBulkRuns' \
    --header 'Accept: application/json' \
    --header 'x-api-key: {{ YOUR API KEY }}' \
    --header 'Content-Type: application/json' \
    --data '{
        "groupId": "{{ YOUR SPELL ID }}",
        
    }'
  ```
</CodeGroup>

The data returned will look like:

<CodeGroup>
  ```json JSON
  {
  	"runs": [
  		{
  			"state": "success",
  			"outputs": {
  				...
  			}
  		},
  		....
  	]
  }
  ```
</CodeGroup>