1. Set up Prerequisites

Generate your API key on Platform. Then, set up with the Python SDK or with cURL:

echo "Install curl and jq via brew, apt, or your favorite package manager"
export PARALLEL_API_KEY="your_api_key_here"

2. Execute your First Task Run

Make your first API request with one of these examples:

You can learn about our available Processors here ->
echo "Creating the run:"
RUN_JSON=$(curl -s "https://api.parallel.ai/v1/tasks/runs" \
-H "x-api-key: ${PARALLEL_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
    "task_spec": {
        "output_schema": "The founding date of the company in the format MM-YYYY"
    },
    "input": "United Nations",
    "processor": "base"
}')
echo "$RUN_JSON" | jq .
RUN_ID=$(echo "$RUN_JSON" | jq -r '.run_id')

echo "Retrieving the run result, blocking until the result is available:"
curl -s "https://api.parallel.ai/v1/tasks/runs/${RUN_ID}/result" \
  -H "x-api-key: ${PARALLEL_API_KEY}" | jq .

Sample Response

Immediately after a Task Run is created, the Task Run object, including the status of the Task Run, is returned. On completion, the Task Run Result object is returned.

Basis, including citations, reasoning - and for advanced Processors excerpts and confidence level - is returned with every Task Run Result.

{
  "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
  "status": "queued",
  "is_active": true,
  "warnings": null,
  "processor": "base",
  "metadata": null,
  "created_at": "2025-04-23T20:21:48.037943Z",
  "modified_at": "2025-04-23T20:21:48.037943Z"
}

3. From Simple to Complex Tasks

The Task API supports a progression of task complexity:

1

Simple Query -> Simple Answer

Simply ask “What was the founding date of the United Nations?” and receive an answer based on web research in plain text. This straightforward approach is illustrated above.

2

Simple Query -> Structured Output

Define a structured output format with founding date, employee count and other desired details for a company, passing in the company name as input.

echo "Creating the run:"
RUN_JSON=$(curl -s 'https://api.parallel.ai/v1/tasks/runs' \
-H "x-api-key: ${PARALLEL_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input": "United Nations",
"processor": "core",
"task_spec": {
"output_schema": {
  "type": "json",
  "json_schema": {
    "type": "object",
    "properties": {
      "founding_date": {
        "type": "string",
        "description": "The official founding date of the company in the format MM-YYYY"
      },
      "employee_count": {
        "type": "string",
        "enum": [
          "1-10 employees",
          "11-50 employees",
          "51-200 employees",
          "201-500 employees",
          "501-1000 employees",
          "1001-5000 employees",
          "5001-10000 employees",
          "10001+ employees"
        ],
        "description": "The range of employees working at the company. Choose the most accurate range possible and make sure to validate across multiple sources."
      },
      "funding_sources": {
        "type": "string",
        "description": "A detailed description, containing 1-4 sentences, of the company'\''s  funding sources., including their estimated value."
      }
    },
    "required": ["founding_date", "employee_count", "funding_sources"],
    "additionalProperties": false
  }
}
}
}'
)
echo "$RUN_JSON" | jq .
RUN_ID=$(echo "$RUN_JSON" | jq -r '.run_id')

echo "Retrieving the run result, blocking until the result is available:"
curl -s "https://api.parallel.ai/v1/tasks/runs/${RUN_ID}/result" \
  -H "x-api-key: ${PARALLEL_API_KEY}" | jq .
3

Structured Input -> Structured Output

Define structured input and output schemas providing founding date, employee count and other desired details for a company name and company website.

echo "Creating the run:"
RUN_JSON=$(curl -s 'https://api.parallel.ai/v1/tasks/runs' \
-H "x-api-key: ${PARALLEL_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input": {
"company_name": "United Nations",
"company_website": "www.un.org"
},
"processor": "core",
"task_spec": {
"output_schema": {
  "type": "json",
  "json_schema": {
    "type": "object",
    "properties": {
      "founding_date": {
        "type": "string",
        "description": "The official founding date of the company in the format MM-YYYY"
      },
      "employee_count": {
        "type": "string",
        "enum":[
          "1-10 employees",
          "11-50 employees",
          "51-200 employees",
          "201-500 employees",
          "501-1000 employees",
          "1001-5000 employees",
          "5001-10000 employees",
          "10001+ employees"
        ],
        "description": "The range of employees working at the company. Choose the most accurate range possible and make sure to validate across multiple sources."
      },
      "funding_sources": {
        "type": "string",
        "description": "A detailed description, containing 1-4 sentences, of the company'\''s  funding sources., including their estimated value."
      }
    },
    "required": ["founding_date", "employee_count", "funding_sources"],
    "additionalProperties": false
  }
},
"input_schema": {
  "type": "json",
  "json_schema": {
    "type": "object",
    "properties": {
      "company_name": {
        "type": "string",
        "description": "The name of the company to research"
      },
      "company_website": {
        "type": "string",
        "description": "The website of the company to research"
      }
    },
    "required": ["company_name", "company_website"]
  }
}
}
}'
)
echo "$RUN_JSON" | jq .
RUN_ID=$(echo "$RUN_JSON" | jq -r '.run_id')

echo "Retrieving the run result, blocking until the result is available:"
curl -s "https://api.parallel.ai/v1/tasks/runs/${RUN_ID}/result" \
  -H "x-api-key: ${PARALLEL_API_KEY}" | jq .

Sample Structured Task Result

{
  "run": {
    "run_id": "trun_0824bb53c79c407b89614ba22e9db51c",
    "status": "completed",
    "is_active": false,
    "warnings": [],
    "processor": "core",
    "metadata": null,
    "created_at": "2025-04-24T16:05:03.403102Z",
    "modified_at": "2025-04-24T16:05:33.099450Z"
  },
  "output": {
    "content": {
      "funding_sources": "The United Nations' funding comes from governments, multilateral partners, and other non-state entities. This funding is acquired through assessed and voluntary contributions from its member states.",
      "employee_count": "10001+ employees",
      "founding_date": "10-1945"
    },
    "basis": [
      {
        "field": "funding_sources",
        "citations": [
          {
            "title": "Funding sources",
            "url": "https://www.financingun.report/un-financing/un-funding/funding-entity",
            "excerpts": [
              "The UN system is funded by a diverse set of partners: governments, multilateral partners, and other non-state funding."
            ]
          },
          {
            "title": "US Funding for the UN",
            "url": "https://betterworldcampaign.org/us-funding-for-the-un",
            "excerpts": [
              "Funding from Member States for the UN system comes from two main sources: assessed and voluntary contributions."
            ]
          }
        ],
        "reasoning": "The United Nations' funding is derived from a diverse set of partners, including governments, multilateral organizations, and other non-state entities, as stated by financingun.report. According to betterworldcampaign.org, the funding from member states is acquired through both assessed and voluntary contributions.",
        "confidence": "high"
      },
      {
        "field": "employee_count",
        "citations": [
          {
            "title": "Funding sources",
            "url": "https://www.financingun.report/un-financing/un-funding/funding-entity",
            "excerpts": []
          }
        ],
        "reasoning": "The UN employs approximately 37,000 people, with a total personnel count of 133,126 in 2023.",
        "confidence": "low"
      },
      {
        "field": "founding_date",
        "citations": [
          {
            "title": "Funding sources",
            "url": "https://www.financingun.report/un-financing/un-funding/funding-entity",
            "excerpts": []
          },
          {
            "title": "History of the United Nations",
            "url": "https://www.un.org/en/about-us/history-of-the-un",
            "excerpts": [
              "The United Nations officially began, on 24 October 1945, when it came into existence after its Charter had been ratified by China, France, the Soviet Union, ..."
            ]
          },
          {
            "title": "The Formation of the United Nations, 1945",
            "url": "https://history.state.gov/milestones/1937-1945/un",
            "excerpts": [
              "The United Nations came into existence on October 24, 1945, after 29 nations had ratified the Charter. Table of Contents. 1937–1945: Diplomacy and the Road to ..."
            ]
          }
        ],
        "reasoning": "The United Nations officially began on October 24, 1945, as stated in multiple sources including the UN's official history and the US Department of State's historical milestones. This date is when the UN came into existence after its Charter was ratified by key member states.",
        "confidence": "high"
      }
    ],
    "type": "json"
  }
}

4. Run Multiple Tasks

For many use cases, knowing how to scale beyond one Task Run is crucial. To execute multiple Task Runs concurrently, we recommend the AsyncParallel Python client:

Python (Async)
import asyncio
import os

from parallel import AsyncParallel
from pydantic import BaseModel, Field
from typing import List

class CountryInput(BaseModel):
    country: str = Field(
        description="Name of the country to research. Must be a recognized "
        "sovereign nation (e.g., 'France', 'Japan')."
    )
    year: int = Field(
        description="Year for which to retrieve data. Must be 2000 or later. "
                    "Use most recent full-year estimates if year is current."
    )

class CountryOutput(BaseModel):
    gdp: str = Field(
        description="GDP in USD for the year, formatted like '$3.1 trillion (2023)'."
    )
    top_exports: List[str] = Field(
        description="Top 3 exported goods/services by value. Use credible sources."
    )
    top_imports: List[str] = Field(
        description="Top 3 imported goods/services by value. Use credible sources."
    )

async def main():
    # Initialize the Parallel client
    client = AsyncParallel(api_key=os.environ.get("PARALLEL_API_KEY"))

    # Prepare structured input
    input_data = [
        CountryInput(country="France", year=2023),
        CountryInput(country="Germany", year=2023),
        CountryInput(country="Italy", year=2023)
    ]

    run_results = await asyncio.gather(*[
        client.task_run.execute(
            input=datum,
            output=CountryOutput,
            processor="core"
        )
        for datum in input_data
    ])

    for run_input, run_result in zip(input_data, run_results):
        print(f"Task run output for {run_input}: {run_result.output.parsed}")

if __name__ == "__main__":
    asyncio.run(main())

Next Steps