Decisions API Quickstart

The Parallel Decisions API takes context and named questions, retrieves web evidence, and returns typed answers with sources. Ask whether a condition is true, choose from a fixed set of options, or score against an ordered rubric. To retrieve pages and excerpts for your own reasoning pipeline, use the Search API.

The Decisions API is also available as the web_decisions tool in the Parallel MCP server, free to use with no account or API key. Connect your MCP client to https://mcp.parallel.ai/mcp, then ask your agent to use Parallel Decisions, for example: “Use Parallel Decisions to check whether Clay offers an official command-line interface (CLI).” Sign in or add an API key for higher limits.

What you can build

The Decisions API is designed for fast, typed answers to questions about the live web, at a cost low enough to run on every record.

CRM enrichment: Refresh employee bands, investors, and product categories across thousands of company records.
Eligibility checks: Screen an application against current program or insurance rules, with web evidence for human review.
Agent guardrails: Check whether a claim is still current before an agent acts, then use answer probabilities to proceed, retry, or escalate.

1. Set Up Prerequisites

Generate your API key on Platform, then export it:

export PARALLEL_API_KEY="PARALLEL_API_KEY"

2. Make Your First Decision

Sample Request

Send the entity or context in state and name each question in questions. The noul question type returns the estimated probability that the condition is true.

curl https://api.parallel.ai/v1/decisions \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "state": {
      "company": "Clay",
      "website": "https://www.clay.com"
    },
    "questions": {
      "has_cli": {
        "type": "noul",
        "instructions": "Does Clay offer an official command-line interface (CLI)?"
      }
    }
  }'

import os

import requests

response = requests.post(
    "https://api.parallel.ai/v1/decisions",
    headers={"x-api-key": os.environ["PARALLEL_API_KEY"]},
    json={
        "state": {
            "company": "Clay",
            "website": "https://www.clay.com",
        },
        "questions": {
            "has_cli": {
                "type": "noul",
                "instructions": "Does Clay offer an official command-line interface (CLI)?",
            }
        },
    },
    timeout=30,
)
response.raise_for_status()
decision = response.json()

answer = decision["answers"]["has_cli"]
if answer["type"] == "refusal":
    print("No decision returned; review this question.")
else:
    print("Estimated probability:", answer["noul"])

for citation in decision["citations"]:
    print(citation["url"])

async function main() {
    const response = await fetch("https://api.parallel.ai/v1/decisions", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": process.env.PARALLEL_API_KEY!,
        },
        body: JSON.stringify({
            state: {
                company: "Clay",
                website: "https://www.clay.com",
            },
            questions: {
                has_cli: {
                    type: "noul",
                    instructions: "Does Clay offer an official command-line interface (CLI)?",
                },
            },
        }),
    });
    if (!response.ok) {
        throw new Error(`Decision failed: ${response.status} ${await response.text()}`);
    }

    const decision = await response.json();
    const answer = decision.answers.has_cli;
    if (answer.type === "refusal") {
        console.log("No decision returned; review this question.");
    } else {
        console.log("Estimated probability:", answer.noul);
    }
    for (const citation of decision.citations) {
        console.log(citation.url);
    }
}

main().catch(console.error);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class DecisionsExample {
    public static void main(String[] args) throws Exception {
        String body = "{"
            + "\"state\":{\"company\":\"Clay\","
            + "\"website\":\"https://www.clay.com\"},"
            + "\"questions\":{\"has_cli\":{\"type\":\"noul\","
            + "\"instructions\":\"Does Clay offer an official command-line interface (CLI)?\"}}}";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.parallel.ai/v1/decisions"))
            .timeout(Duration.ofSeconds(30))
            .header("Content-Type", "application/json")
            .header("x-api-key", System.getenv("PARALLEL_API_KEY"))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException("Decision failed: " + response.statusCode()
                + " " + response.body());
        }
        System.out.println(response.body());
    }
}

mode is optional and defaults to fast. You can ask up to 100 related questions in one request, including a mix of predicate, choice, and score questions. They share one set of retrieved evidence. See Question Types.

Each question, including the shared state, may use at most 32,000 estimated input tokens.

Sample Response

Response from a live request:

{
  "mode": "fast",
  "answers": {
    "has_cli": {
      "type": "noul",
      "noul": 0.9992643798509062
    }
  },
  "usage": {
    "input_tokens": 4212,
    "output_tokens": 0
  },
  "citations": [
    {
      "url": "https://developers.clay.com/concepts/cli-basics",
      "title": "CLI basics",
      "excerpts": [
        "Understand the Clay CLI output contract, exit codes, environment variables, and authentication.\nThe Clay CLI (clay) is JSON-first: every command writes machine-readable JSON to stdout on success and a structured error envelope to stderr on failure.\nThere are no spinners, colors, or progress bars, so agents and scripts can branch on the output and exit code directly.\nclay login opens a browser to authorize the CLI with OAuth — this works from a human terminal or an agent's shell tool. Use clay whoami as the canonical check that authentication is working, and clay logout to clear a stored credential.\nEach sign-in covers one workspace — the one you pick on the consent screen.\nTo work across several, run clay login once per workspace: signing into a second keeps the first. clay workspaces list shows what you are signed into, clay workspaces current shows which one commands run against, and clay workspaces switch <id> switches."
      ]
    },
    {
      "url": "https://university.clay.com/docs/cli-security-privacy",
      "title": "CLI security & privacy - Clay Docs",
      "excerpts": [
        "Understand CLI authentication, role requirements, and how Clay handles data sent from your terminal.\nOverview\nClay's CLI lets your team drive a Clay workspace from a terminal or coding agent instead of the UI.\nBecause that means credentials live on a local machine and commands run outside the app, admins need to know who can sign in and what those sessions can reach.\n‍\nNote: The CLI is part of Clay's Agent Plugin, which is in open beta and currently supported on Mac and Linux. Windows is not supported during the beta.\n‍\nHow CLI sessions are authenticated\nThe recommended path is browser-based OAuth:\nTreat that file like any other credential on disk — it is not stored in your operating system's keychain.\n* Running clay logout clears the stored credentials for that machine.\nAPI keys are for calling the Clay public API directly — they don't sign in to the CLI.\nThe supporting documentation — the SOC 2 Type II report, the current AI subprocessor list, and security questionnaire responses — is available through the Clay Trust Center , or by contacting security@clay.com .\nYour responsibilities:\n* Decide who gets CLI access — CLI access implies edit rights on the workspace. Grant Editor deliberately.\nHow Clay handles data sent through the CLI\nWhen your team runs a CLI command:\nFAQs\nIf we drive the CLI from a coding agent, what does that agent's provider see?\nThe CLI itself communicates only with Clay. But when you run it through a coding agent, whatever you type into that agent — and whatever command output it reads back — is processed by that agent's provider under your agreement with them, not Clay's.\n* Do not sell my data\n© Clay 2025 – Born in Brooklyn. Claymation illustrations by the wonderful Hudson Christie ."
      ]
    },
    {
      "url": "https://docs.clayplatform.io/claycli/docs/cli.html",
      "title": "Claycli · Clay CLI",
      "excerpts": [
        "Clay CLI ### 3.9.1\n* GitHub\nClaycli\nThis is the Clay command line utility. Here we will provide you with documentation and examples that will help you to run all the functionalities that you need. ##  Installation To install claycli you just need to type the following command: ``` $ npm install -g claycli\nClay CLI ### 3.9.1\n> [](#usage) Usage If installed globally, call `clay` from the command line with the [command](#commands) and `options` that you need. ```\nClay CLI ### 3.9.1\n$ clay < command > [options]\n`Much like `git` ; `claycli` is configured using a [dotfile](https://medium.com/@webprolific/getting-started-with-dotfiles-43c3602fd789) ( `.clayconfig` ) in your home folder. In it, you may specify references to api keys and `urls / site prefixes` that you use frequently.\nClay CLI ### 3.9.1\nFor `urls` and `site prefixes` , it will assume `http://` and port `80` unless you specify otherwise. Note that a `_site prefix_` is everything before the api route, e.g. `http://domain.com/site1` in `http://domain.com/site1/_components/article` .`\n[keys]\nlocal  = ha8yds9a8shdf98asdf\nqa  =  8 quwqwer09ewr0w9uer\nClay CLI ### 3.9.1\nprod  = bj34b6345k634jnk63n4\n[urls]\nlocal-site1  = https://localhost.site1.com: 3001 local-site2  = site2.com/site- 2 # http and port 80\nClay CLI ### 3.9.1\n``` For smaller `Clay` installations (or, ironically, for very large teams where devs spend most of their time on individual sites), you may specify a default api key and `url / site prefix` by using the `CLAYCLI_DEFAULT_KEY` and `CLAYCLI_DEFAULT_URL` environment variables. ## [](#commands) Commands * [`config`](#config)\nClay CLI ### 3.9.1\n* [`lint`](#lint)\n* [`import`](#import)\n* [`export`](#export)\n* [`compile`](#compile)"
      ]
    },
    {
      "url": "https://university.clay.com/fr/docs/audiences-for-agents",
      "title": "Audiences for agents and the CLI - Clay Docs",
      "excerpts": [
        "Audiences for agents and the CLI\nRead, segment, and manage your workspace's people, companies, and deals from the Clay CLI — and from the Clay agents that run it for you.\nOverview\nAudiences is the home for your workspace's own people, companies, and deals.\nThe clay audiences command group brings those records to your terminal: you can create and edit segments, manage field definitions, count or read records, and read the activities and signal events attached to them — all without opening the Clay app.\n‍\nNote: These commands need Audiences enabled for your workspace, plus the Clay Agent Plugin installed and signed in. Install and sign-in steps live in the plugin doc, linked below.\n‍\n* The Clay CLI — you or your coding agent run clay audiences commands directly in a terminal.\n* Sculptor — Clay's in-app go-to-market co-pilot runs the same commands for you when you ask it about your records.\n* The Agent surface in Clay — runs the same commands while it reasons through a play and builds the workflow.\nFAQs\nDoes reading Audiences from the CLI cost credits?\nNot today — Audiences is CLI-only, and no MCP tool serves it. Reps who connect a chat app to Clay over MCP get people and company search plus any Functions your team has enabled, and admins can additionally let them query owned accounts and opportunity data from the CRM. See MCP in Clay for how that access is configured.\nDo Clay's in-app agents really run the same commands?\nYes. All three surfaces load the same Audiences instructions from the Clay Agent Plugin, so a capability that lands in the CLI reaches Sculptor and the Agent surface with it. That's also why the limitations above apply everywhere rather than to the terminal alone.\nHow do I copy a segment?"
      ]
    },
    {
      "url": "https://developers.clay.com/quickstart",
      "title": "Quickstart - Clay docs",
      "excerpts": [
        "Build with Clay from your coding agent, or call the Clay API from your own applications.\nThere are two ways to use Clay as a developer: install the agent plugin to build with Clay inside your coding agent, or call the Public API directly from your own applications and services.\nAgent plugin\nThe agent plugin gives your coding agent Clay's skills and the clay CLI — the fastest way to build with Clay from a coding agent.\nIt requires a coding-agent host with a shell — Claude Code, Codex, or Cursor — and doesn't work in general-purpose chat apps like Claude Desktop, claude.ai, or ChatGPT that can't run the CLI.\nCopy this into your agent of choice and let it install and set up the plugin for you:\nSet up the Clay plugin by following the steps in\nhttps://github.com/clay-run/agent-plugins\nThis runs the plugin's setup skill, which puts clay on your PATH, signs you in, and verifies the CLI. Sign-in opens a browser to authorize the CLI.\nAgent plugin repository\nAPI\nUse the Public API to call Clay from your own applications and services — backend jobs, internal tools, queues, and product features. Requests authenticate with a Clay API key in the clay-api-key header.\nAPI reference\nEndpoint paths, request bodies, response schemas, and an interactive try-it console.\nGet an API key\n* Ask your agent to generate one for you after installing the agent plugin.\n* Run clay api-keys create --name \"<key name>\" with the clay CLI. The key is returned once, in the apiKey field.\n* Create one yourself in Clay under API and CLI → API keys.\nKeep keys server-side."
      ]
    },
    {
      "url": "https://www.clay.com/agent-plugin",
      "title": "Clay CLI: Build on Clay with any coding agent | clay.com",
      "excerpts": [
        "description: Use Clay's CLI to build workflows and governance directly into your GTM system. Build in Clay directly via a coding agent with CLI. title: \"Clay CLI: Build on Clay with any coding agent | clay.com\" image: https://cdn.prod.website-files.com/61477f2c24a826836f969afe/6a4fbb2bf6b13e7ff04d15c7_open%20graph%20cli%20api.jpg\nAgent plugin\nBuild on Clay with any coding agent\nUse Clay's API to build Clay data, workflows, and governance directly into your GTM system. Build in Clay directly via a coding agent with CLI.\nInstall the Clay Plugin to start building\nCopy and paste into your agent of choice\nSet up the Clay plugin by following the steps in https://github.com/clay-run/agent-plugins\nCopied\nCall any functions, workflows, and Claygents from Clay's API so your coding agent references centrally governed GTM logic — including lead scoring and outbound copy — instead of rebuilding one-offs.\nGet started\nUse Case 03 — WORKFLOW AUTOMATION\nVibecode GTM workflows\nBuild workflows in natural language via Clay CLI, then manage observability in-product, using Clay Workflows.\nGet started\nBuild on Clay with any coding agent\nInstall the Clay Plugin and start building data, workflows, and governance into your GTM system.\nInstall the Clay Plugin to start building\nCopy and paste into your agent of choice\nSet up the Clay plugin by following the steps in https://github.com/clay-run/agent-plugins\nCopied\nDeveloper docs\npress Enter to run — press R to reset\n{\n\"@context\" : \"https://schema.org\",\n\"@type\" : \"WebSite\",\n\"name\" : \"Clay\",\n\"alternateName\" : \"Clay\",\n\"url\" : \"https://clay.com/\"\n}"
      ]
    },
    {
      "url": "https://university.clay.com/docs/clay-api-cli?dub_id=DHFbP3TR3TaCG4pm",
      "title": "Installing Clay Plugin (API & CLI) - Clay Docs",
      "excerpts": [
        "Head to Guide: Using Clay Plugin for go-to-market plays you can run once the Plugin is connected — source your market, score it for fit, and route who gets worked first.\n‍\nNote: The Plugin installs Clay’s skills and the Clay CLI into your coding agent.\nFor the full CLI quickstart, Public API setup, code examples, and guides for Searches, Routines, and Workflows, see developers.clay.com .\nThey're separate surfaces, not two halves of one product. The Plugin installs Clay's skills and the Clay CLI into your coding agent, and the CLI is what you or your agent run in a shell for one-off runs, scripting, and inspecting data. It authenticates with the session created by clay login , so there's no separate key to configure.\nCan I build or write to Clay tables via CLI or API?\nThere are no current plans to support table building from the API or CLI.\nCan I build Workflows with the API or CLI?\nYes, Workflows are available from the CLI and Plugin in Beta . For production use, Clay-managed functions and custom functions are the more stable option.\nAre credit budgets available via the developer platform?\nUse Company URL Finder in Clay to turn a company name into that company's website domain.\nView article\nView article View article\nSettings & admin\nIP access restrictions\nRead, segment, and manage your workspace's people, companies, and deals from the Clay CLI — and from the Clay agents that run it for you.\nView article\nView article View article\nOther popular resources\nExperts\nFind a Clay Expert\nExplore our network of Clay experts and agencies.\nView experts\nView experts View experts\nCommunity\n* Do not sell my data\n© Clay 2025 – Born in Brooklyn. Claymation illustrations by the wonderful Hudson Christie ."
      ]
    },
    {
      "url": "https://developers.clay.com/",
      "title": "Overview - Clay docs",
      "excerpts": [
        "Use Clay from agents, terminals, backend services, internal tools, and custom apps.\nClay used to live primarily in the Clay UI. Now Clay also works where your agents, developers, and business systems already are.\nUse the developer platform to search Clay's GTM data, run reusable Clay logic, read table data, and work with Audiences programmatically.\nStart here\nInstall the Clay plugin\nBest for Claude Code, Codex, Cursor, and agent-first work. The plugin ships skills and the Clay CLI.\nCall the API directly\nBest for backend jobs, internal tools, custom apps, queues, and product workflows.\nCore primitives\n* Primitive | Use it for\n* Searches | Find companies and people using Clay's GTM database\n* Routines | Run Clay-managed functions, custom functions, and Workflows\n* Tables (Enterprise) | Query existing Clay table data from known tables\n* Audiences | Work with records, saved segments, activities, and signal events\nRun a search, then enrich with a function\nPull a target list from Clay data, then run Clay-managed functions on the results.\nGive an agent access to a Clay function\nLet an agent call Clay logic as part of its normal work.\nBuild a Workflow (Alpha)\nCreate, edit, validate, run, and inspect a Workflow from the plugin or CLI."
      ]
    },
    {
      "url": "https://university.clay.com/fr/docs/clay-api-cli",
      "title": "Installing Clay Plugin (API & CLI) - Clay Docs",
      "excerpts": [
        "Installing Clay Plugin (API & CLI)\nHead to Guide: Using Clay Plugin for go-to-market plays you can run once the Plugin is connected — source your market, score it for fit, and route who gets worked first.\n‍\nNote: The Plugin installs Clay’s skills and the Clay CLI into your coding agent.\n* A paid coding agent plan: Claude (Pro, Max, Team, or Enterprise) for Claude Code, or ChatGPT (Plus, Pro, Business, Edu, or Enterprise) for Codex. If your company manages Claude, check that Claude Code is enabled for you.\n* Editor or Admin access in the Clay workspace you'll connect.\n* On Windows, admin rights (or help from IT) for one step.\n‍\n* Plan | Search results per request | Total search results\n* Free | 50 | 100/mo\n* Trial | 50 | 10k per 14 days\n* Paid self-serve plans | 500 | 1M/yr\n* Enterprise | 500 | 10M/yr\nFAQs\nDoes using the API or CLI cost extra credits?\nThe Plugin gives agent environments (Claude Code, Codex, Cursor) Clay's skills and the Clay CLI — the fastest path for agent-first and interactive coding workflows. The Public API is better suited for background jobs and your own apps, where you want to call Clay directly instead of installing anything.\nThe Public API uses its own key rather than your CLI sign-in. Create one with the clay api-keys create command — the key is shown only once, so store it somewhere safe.\nThey're separate surfaces, not two halves of one product. The Plugin installs Clay's skills and the Clay CLI into your coding agent, and the CLI is what you or your agent run in a shell for one-off runs, scripting, and inspecting data. It authenticates with the session created by clay login , so there's no separate key to configure.\nCan I build or write to Clay tables via CLI or API?\nThere are no current plans to support table building from the API or CLI."
      ]
    },
    {
      "url": "https://university.clay.com/docs/clay-api-cli",
      "title": "Installing Clay Plugin (API & CLI) - Clay Docs",
      "excerpts": [
        "Head to Guide: Using Clay Plugin for go-to-market plays you can run once the Plugin is connected — source your market, score it for fit, and route who gets worked first.\n‍\nNote: The Plugin installs Clay’s skills and the Clay CLI into your coding agent.\n* A paid coding agent plan: Claude (Pro, Max, Team, or Enterprise) for Claude Code, or ChatGPT (Plus, Pro, Business, Edu, or Enterprise) for Codex. If your company manages Claude, check that Claude Code is enabled for you.\n* Editor or Admin access in the Clay workspace you'll connect.\n* On Windows, admin rights (or help from IT) for one step.\n‍\nThere is no additional cost to use the Plugin.\nThe Plugin also gives you access to:\n* Audiences — Read and segment the workspace's own people, companies, and deals. See Audiences for agents and the CLI .\n* Searches — Find companies and people using structured filters over Clay's GTM dataset. Learn more about Searches in this video walkthrough .\nFAQs\nDoes using the API or CLI cost extra credits?\nNo. API and CLI calls consume the same credits and actions as the equivalent work done in-product. There is no additional cost because work is triggered via the developer platform instead of the UI.\nWhat's the difference between the Plugin and the Public API?\nThe Plugin gives agent environments (Claude Code, Codex, Cursor) Clay's skills and the Clay CLI — the fastest path for agent-first and interactive coding workflows. The Public API is better suited for background jobs and your own apps, where you want to call Clay directly instead of installing anything.\nThe Public API uses its own key rather than your CLI sign-in. Create one with the clay api-keys create command — the key is shown only once, so store it somewhere safe.\nCan I build or write to Clay tables via CLI or API?"
      ]
    }
  ],
  "decision_id": "decisions_34b4be1b1405e19ba5516d9bb76c56ad"
}

3. Use the Answer and Sources

Find the answer by the name you supplied: answers.has_cli. A noul value of 0.9992643798509062 is an estimated 99.93% probability, not a boolean. Every question can return {"type": "refusal"} instead of providing an answer, which is a successful response, not an HTTP error. Check type before reading the answer. The citations array contains sources for the whole call. It does not map individual sources to answers. Each citation includes a url and an excerpts array, with an optional title. See the citation field definitions.

Next Steps

Question Types: predicates, choices, scores, and refusals
Best Practices: shared evidence, citations, and limits
Pricing: per-request cost
Rate Limits: default quotas per product
API Reference: request and response schemas
Parallel MCP: the web_decisions tool for agents

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

Decisions API Quickstart

What you can build

1. Set Up Prerequisites

2. Make Your First Decision

Sample Request

Sample Response

3. Use the Answer and Sources

Next Steps

​What you can build

​1. Set Up Prerequisites

​2. Make Your First Decision

​Sample Request

​Sample Response

​3. Use the Answer and Sources

​Next Steps

What you can build

1. Set Up Prerequisites

2. Make Your First Decision

Sample Request

Sample Response

3. Use the Answer and Sources

Next Steps