Many applications don’t need a long answer. They need a decision: which team owns a support ticket, whether a product photo shows damage, or how urgent a request is. The OpenAI Decisions API is built for this job. You send shared evidence such as text, images, or JSON, define the questions you want answered, and receive typed results your code can use directly.
OpenAI launched the API as a public beta on October 6, 2026. The official developer guide now describes it as generally available. This guide covers prerequisites, a working Python request, the three question types, practical examples, current pricing, and how the API compares with the Responses API.
OpenAI Decisions API: Key Takeaways
- The API answers bounded questions about text, images, or JSON and returns typed results instead of prose.
- It supports three answer types: predicate (a probability from 0 to 1), choice (one of your options, with probabilities and confidence), and score (a weighted average across ordered levels).
- Setup requires an OpenAI API key stored in an environment variable, the OpenAI Python SDK, and a clearly defined decision to test.
- With gpt-6-luna, uncached input costs $0.10 per million tokens, and output tokens are not charged. Cached reads and cache writes have separate rates.
- It fits routing, classification, condition checks, and prioritization, where a bounded answer is enough.
- Answers are estimates. Set thresholds from labeled examples and send costly or uncertain cases to a person.
What Is the OpenAI Decisions API?
The Decisions API accepts shared evidence and one or more questions. Each question asks for a bounded answer, and the response returns answers in question order. Your application then acts on the result, such as routing a ticket, flagging a photo for review, or choosing the next step in an agent workflow.
Choice questions handle classification and routing. Predicate questions check conditions. Score questions rate inputs against a rubric. Several questions can share one input in a single request, and each question can include its own images.
OpenAI reports that the endpoint returns decisions up to 10 times faster than calling GPT-6 Luna through the Responses API. That figure comes from OpenAI and is not independently verified. Actual latency depends on input size, question count, and network conditions, so measure it on your own workload.
The basic flow is:
Input and context → defined questions → typed answers → application logic
The API is designed for focused decisions, not open-ended generation. If you need a written explanation or an object that follows your own schema, the Responses API with Structured Outputs is the better fit.
What You Need Before Using the OpenAI Decisions API
Prepare four things before your first request:
- An OpenAI API account with API access and a secret key. The API quickstart covers setup.
- Python with the OpenAI SDK installed.
- A decision stated as a question with a clear meaning for pass and fail.
- Twenty to fifty representative inputs with known correct answers. You will use them to choose thresholds.
Keep the API key out of source code and version control. An environment variable keeps it out of your files, and a secrets manager is the better choice for production systems.
How to Set Up the OpenAI Decisions API
Step 1: Configure Your OpenAI API Key
Export the key in the terminal session where you run your code.
macOS or Linux:
bash
export OPENAI_API_KEY=”your-api-key”
Windows PowerShell:
powershell
$env:OPENAI_API_KEY=”your-api-key”
The OpenAI Python client reads OPENAI_API_KEY automatically, so you don’t need to pass the key in code.
Step 2: Install the OpenAI Python SDK
Install or upgrade the SDK:
bash
pip install –upgrade openai
The reference pages I reviewed don’t state a minimum SDK version, so install the current release. The OpenAI SDK page lists the supported SDKs for other languages.
Step 3: Make Your First Decisions API Request
This example follows the official guide’s choice-question pattern and sends a request to POST /v1/decisions:
python
from openai import OpenAI
client = OpenAI() # Reads OPENAI_API_KEY from the environment
decision = client.decisions.create(
model=”gpt-6-luna”, # The only currently supported model
input=”I was charged twice for my order.”, # Shared evidence for all questions
questions=[
{
“type”: “choice”,
“name”: “department”, # Identifies this answer in the response
“instructions”: “Which department should handle this complaint?”,
“choices”: [
{“value”: “billing”, “description”: “Payments, invoices, and refunds.”},
{“value”: “technical”, “description”: “Problems using the product.”},
{“value”: “shipping”, “description”: “Delivery and tracking.”},
{“value”: “other”, “description”: “Requests outside these categories.”},
],
}
],
)
answer = decision.answers[0]
if answer.type == “refusal”:
print(f”Refused: {answer.name}”)
elif answer.type == “choice”:
print(f”Department: {answer.choice} (confidence: {answer.confidence})”)
Each question needs a type, a unique name, and instructions. Choice questions also need a choices list. Clear option descriptions make the boundaries between categories easier to judge.
Step 4: Understand the API Response
The following excerpt is illustrative, not a recorded run:
json
{
“answers”: [
{
“type”: “choice”,
“name”: “department”,
“choice”: “billing”,
“probabilities”: [
{ “value”: “billing”, “probability”: 0.95 },
{ “value”: “technical”, “probability”: 0.02 },
{ “value”: “shipping”, “probability”: 0.01 },
{ “value”: “other”, “probability”: 0.02 }
],
“confidence”: 0.93
}
]
}
The choice field holds one of your supplied values. probabilities lists the estimate for each option, and confidence is a separate value. Any question can return a refusal instead of an answer, while other questions in the same request still return results. Check the type field for every answer.
Step 5: Test Your Questions in the Playground
Before you integrate, test your questions in the Decisions Playground. Run representative inputs and edge cases, and compare the answers with your expected results. Refine the instructions and option descriptions until the behavior matches your criteria, then move the same definitions into your application.
Understanding the Three Decisions API Question Types
| Type | Use it to | Returned result | Example |
| predicate | Check a condition | probability: estimate from 0 to 1 that the condition is true | Does this product photo show visible damage? |
| choice | Select one option | choice, a probability for each option, and confidence | Which department should handle this ticket? |
| score | Rate against ordered levels | Weighted average of level indices, level probabilities, and confidence | How severe is this software issue? |
Predicate Questions
A predicate estimates how likely a statement about the input is to be true. Phrase the instruction as one observable condition, such as whether a product shows a crack, tear, or dent. The probability is an estimate, not a guarantee, so choose your threshold from test data.
Choice Questions
A choice question selects one value from the options you define and returns a probability for each option, plus a confidence value. Use it for categories without a natural order. Include a fallback option such as other so unusual inputs don’t get forced into a poor fit.
Score Questions
A score question rates an input against two to ten ordered levels, indexed from 0. The returned score is the probability-weighted average of those indices, so it can fall between levels. If the level probabilities are 0.1, 0.7, and 0.2, the score is 1.1. Because this is an average of model probabilities, validate any threshold before treating it as a formal risk measure.
OpenAI Decisions API Examples and Use Cases
Example 1: Classify and Route Customer Support Tickets
A support team has four queues: billing, technical, shipping, and other. A choice question with those options routes each ticket. High-confidence answers go straight to the queue, and low-confidence tickets go to a triage queue for a person. Set the cutoff from labeled tickets, weighing the cost of a misroute against the cost of slower handling.
Example 2: Detect Product Damage From Images
A marketplace wants to flag damaged items before shipping. A predicate question paired with the product photo can ask whether the item shows visible damage, such as a crack, tear, or dent, while ignoring shadows and packaging damage. Images can be inline base64 data URLs or public HTTP or HTTPS URLs, but file_id references aren’t supported. Because a missed defect can reach a customer, send photos above your threshold to a human inspector, and test the threshold against photos with known outcomes.
Example 3: Score and Prioritize Incoming Tasks
An engineering team wants bug reports sorted by severity. A score question with three levels (cosmetic, workaround available, and fully blocked) can produce a value for each report. Give each level criteria an observer can check, such as whether a task fails and whether another path exists. Vague labels make levels harder to separate. Sort the queue by score, and review reports that fall between levels.
Example 4: Ask Multiple Questions in One Request
Some decisions share the same input. A product photo might need a damage check, a category check, and a return-eligibility check. Place these in one questions array. A request accepts 1 to 400 questions, up from 200 during the public beta. If a decision depends on an earlier answer, send a separate request. For structured records, use an input_json part in a user message rather than converting the record to a string. Keys inside the JSON are treated as data and don’t trigger image fetches or create messages.
OpenAI Decisions API Pricing Explained
For gpt-6-luna, uncached input costs $0.10 per million tokens, and output tokens are not charged. Prompt caching adds separate rates. The table uses the standard gpt-6-luna rates from OpenAI’s pricing page, which the Decisions guide says apply to this endpoint.
| Charge | Rate per 1M tokens |
| Uncached input | $0.10 |
| Cached input (cache read) | $0.01 |
| Cache write, 30-minute retention | $0.125 |
| Cache write, 12-hour retention | $0.25 |
| Output tokens | Not charged |
Two surcharges can apply. Regional processing endpoints carry a 10% uplift on eligible models, and long-context inputs are subject to multipliers. Check the pricing page for current thresholds. The Decisions guide doesn’t describe how to choose a retention window, so confirm that setting in the prompt caching guide before budgeting for cache writes.
How to Estimate Your API Costs
Assume 10,000 requests per month. Each request sends 1,500 input tokens, and the first 1,200 are a shared reference that stays identical across requests. Question text falls outside the cached prefix.
Without caching: 10,000 × 1,500 = 15 million tokens × $0.10 per million = $1.50.
With caching: 10,000 × 1,200 = 12 million cached tokens × $0.01 per million = $0.12, plus 10,000 × 300 = 3 million uncached tokens × $0.10 per million = $0.30. The total is $0.42, before cache-write charges and any regional or long-context surcharges.
The shared prefix must contain at least 1,024 tokens to be cached. To track usage, call GET /v1/organization/usage/decisions with an admin key that has the api.usage.read permission. Its num_model_requests field counts requests, not questions, so a request with five questions counts once.
OpenAI Decisions API vs. Responses API
| Decisions API | Responses API | |
| Primary purpose | Typed answers to bounded questions | Generated responses, including text and schema-shaped output |
| Output style | Probabilities, one choice with confidence, or a weighted score | Generated text or output that follows your schema |
| Best-fit tasks | Routing, classification, condition checks, prioritization | Explanations, extraction, drafting, tool calls |
| Schema design | You define questions with types, choices, or levels | You define the output schema or tool arguments |
| Cost considerations | Input tokens only on gpt-6-luna | Input, cached input, and output tokens |
| Flexibility | Narrow by design | Broad |
Choose the Decisions API when every answer maps to a label, probability, or rating your code can act on. Choose the Responses API for natural-language output, custom objects, or tool calling. Per token, the same model costs less on Decisions because output isn’t charged, but that comparison only applies to work that fits a bounded answer.
Best Practices, Limitations, and Common Mistakes
- Write each question around one observable condition.
- Make choice options distinct, and include a fallback such as other.
- Define score levels with criteria that adjacent levels can separate.
- Build a labeled test set from real application data before setting thresholds.
- Pick thresholds by weighing false positives against false negatives.
- Route uncertain or high-impact cases to a person, and handle refusals in code.
- Monitor token usage, request counts, latency, and decision quality over time.
- Keep shared context identical across requests to benefit from caching.
- Review data controls. Zero Data Retention and HIPAA use are available to eligible customers, and regional processing is supported in the United States and Europe.
The API limits outputs to bounded answers, but it doesn’t remove errors, guarantee calibrated confidence, or replace validation in your application. Treat confidence values as signals to test, not as ground truth.
Final Verdict
The Decisions API is strongest when your application needs a label, probability, or rating it can act on quickly. Its bounded output format and the need for validation are the main limits. Start by testing one frequent decision in the Playground against 20 to 50 labeled examples. When the threshold and fallback path hold up, move the same questions into your code.
Frequently Asked Questions
What Is the OpenAI Decisions API Used For?
It answers focused questions about text, images, or JSON and returns typed results. Common uses include routing tickets, checking visible damage, and prioritizing work by severity. Results come back as probabilities, a chosen option, or a rubric score.
How Do You Use the OpenAI Decisions API in Python?
Install the OpenAI SDK, set OPENAI_API_KEY, and call client.decisions.create with model=”gpt-6-luna”, an input, and a list of questions. Then read the answers array and check each answer’s type. The complete request is shown in Step 3.
Is the OpenAI Decisions API Generally Available?
According to OpenAI’s Decisions guide, yes. The API launched as a public beta on October 6, 2026, and the guide now lists features added since then. Check the guide for current status before you deploy.
How Much Does the OpenAI Decisions API Cost?
With gpt-6-luna, uncached input costs $0.10 per million tokens, and output tokens are not charged. Cached input costs $0.01 per million tokens, and cache writes cost $0.125 or $0.25 per million tokens depending on retention. Regional and long-context surcharges can apply.
Which Model Does the Decisions API Support?
The official guide lists gpt-6-luna as the only supported model, so use that exact string in the model field. Support can change, so confirm against the guide before launch.
Can the OpenAI Decisions API Process Images and JSON?
Yes. Inputs can include text, images, or both, and JSON can be passed in an input_json part in a user message. Images must be inline base64 data URLs or public HTTP or HTTPS URLs.
How Many Questions Can One Decisions API Request Contain?
A request can contain between 1 and 400 questions. Questions in one request share the same input. If a question depends on another answer, send a separate request.
What Is the Difference Between the Decisions API and the Responses API?
The Decisions API returns typed answers to bounded questions, such as probabilities, a chosen option, or a score. The Responses API generates responses, including output that follows your own JSON schema. Use Decisions for classification and routing, and Responses for open-ended or structured generation.