---
title: "Decisions"
method: POST
path: "/v1/decisions"
tags: ["Decisions"]
---

# Decisions

`POST /v1/decisions`

## Request

- Base URL: `https://api.parallel.ai`
- URL: `https://api.parallel.ai/v1/decisions`
- Auth: API key in header `x-api-key`

Answer typed questions using current web evidence.

## Request body

- GroundedDecisionRequest
  - `advanced_settings` AdvancedDecisionSettings: Advanced configuration for decision grounding.
    - `location` string, nullable: Supported ISO 3166-1 alpha-2 country code for geo-targeted search results. Case-insensitive; normalized to lowercase. Invalid or unsupported codes return a validation error.
    - `include_excerpts` boolean: Whether citations include the excerpts used to ground the decision. When false, every citation has an empty excerpts array.
  - `mode` 'fast': Decision execution mode.
  - `state` unknown, required
  - `questions` object, required: 1 to 100 questions keyed by names containing only ASCII letters, numbers, underscores, and hyphens. State plus the largest question may use at most 32,000 estimated input tokens. Each value is a predicate (`noul`), choice, or score question.

## Response `200`

Successful Response

- GroundedDecisionResponse
  - `mode` 'fast', required
  - `answers` object, required: Answers keyed by the question names from the request. Any question can return a refusal.
  - `usage` GroundedDecisionUsage, required
    - `input_tokens` integer, required
    - `output_tokens` 0, required: Always 0 for compatibility with the upstream contract.
  - `citations` GroundedDecisionCitation[], required: Web sources included in the shared decision context. Applies to the whole request, without a per-answer source mapping. Can be empty.
    - `url` string, required: Source page URL.
    - `title` string, nullable: Page title. Omitted when unavailable.
    - `excerpts` string[], required: Passages used to ground the decision. Empty when advanced_settings.include_excerpts is false.
  - `decision_id` string, required: Decision ID: `decisions_` followed by a UUID without hyphens. Include this ID when reporting an issue or giving feedback so we can find the request's logs and trace.

## Other responses

- `422`: Request validation error

## Changes

- **2026-11-01** `0c1c1b0442dd`: 1 warning, 1 info
  - removed the request property `include_excerpts`
  - added the new optional request property `advanced_settings`
- **2026-10-27** `9be668eecb5d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1/decisions/post.md)

---

[API](https://skmtc.dev/parallel-web/apis/parallel-api.md) - [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parallel-web/apis/parallel-api/revisions/eae6def9641f?raw)