Estimate Disposition Cost
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates"
headers = {"authorization": "<authorization>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "541b9cf3-77fa-4f99-95de-356e656c5670",
"dispositionId": "16fc16fe-92af-4e8b-9459-28e10b05f287",
"draftRevision": 3,
"perValue": [
{
"valueId": "91b9a987-ee08-4018-a433-5a7a5d03dade",
"executionPath": "Judge · Automatic Intelligence",
"usdPerCall": { "min": "0.0121", "expected": "0.0198", "max": "0.0312" }
},
{
"valueId": "a1756910-0ff1-48be-8eb9-635c8bdfd533",
"executionPath": "Structured extraction · Medium Intelligence + corrected transcript (once per call, shared)",
"usdPerCall": { "min": "0.0018", "expected": "0.0031", "max": "0.0049" }
}
],
"totalUsdPerCall": { "min": "0.0139", "expected": "0.0229", "max": "0.0361" },
"assumptions": {
"averageDurationSeconds": 254,
"timing": "immediate",
"modelCostRange": "usage_scenarios",
"customCode": {
"billingPolicy": "monthly_free_tier",
"monthlyFreeInvocations": 1000,
"listPriceUsdPerInvocation": "0.0010",
"freeTierScope": "organization"
}
},
"quoteConfigVersion": "v3-intelligence-routing"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "SERVICE_UNAVAILABLE",
"message": "Disposition pricing is temporarily unavailable"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition not found"
}
]
}
Dispositions
Estimate Disposition Cost
Estimate a disposition’s per-call cost before publishing.
POST
/
v2
/
agents
/
{agent_id}
/
dispositions
/
{disposition_id}
/
estimates
Estimate Disposition Cost
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates"
headers = {"authorization": "<authorization>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/estimates")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"data": {
"id": "541b9cf3-77fa-4f99-95de-356e656c5670",
"dispositionId": "16fc16fe-92af-4e8b-9459-28e10b05f287",
"draftRevision": 3,
"perValue": [
{
"valueId": "91b9a987-ee08-4018-a433-5a7a5d03dade",
"executionPath": "Judge · Automatic Intelligence",
"usdPerCall": { "min": "0.0121", "expected": "0.0198", "max": "0.0312" }
},
{
"valueId": "a1756910-0ff1-48be-8eb9-635c8bdfd533",
"executionPath": "Structured extraction · Medium Intelligence + corrected transcript (once per call, shared)",
"usdPerCall": { "min": "0.0018", "expected": "0.0031", "max": "0.0049" }
}
],
"totalUsdPerCall": { "min": "0.0139", "expected": "0.0229", "max": "0.0361" },
"assumptions": {
"averageDurationSeconds": 254,
"timing": "immediate",
"modelCostRange": "usage_scenarios",
"customCode": {
"billingPolicy": "monthly_free_tier",
"monthlyFreeInvocations": 1000,
"listPriceUsdPerInvocation": "0.0010",
"freeTierScope": "organization"
}
},
"quoteConfigVersion": "v3-intelligence-routing"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "SERVICE_UNAVAILABLE",
"message": "Disposition pricing is temporarily unavailable"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition not found"
}
]
}
Overview
Dispositions are enabled per organization. If your organization does not have access, these endpoints return
404.id is a digest of the draft, its pinned dependencies, and the current pricing basis, so the same draft always yields the same id, and any change yields a new one. Pass the id as estimateId to Publish Disposition, which recomputes it and rejects a stale one.
Requires an admin, owner, operator, or prompter role.
Headers
string
required
Your API key for authentication.
Path Parameters
string
required
The agent’s unique identifier. Must be a UUID; otherwise returns
400 with the message agentId must be a valid UUID. Returns 404 Agent not found if the agent is not in your organization.string
required
The disposition’s unique identifier. Must be a UUID; otherwise returns
400 with the message dispositionId must be a valid UUID. Returns 404 Disposition not found if it does not belong to this agent.Response
All money fields are USD per processed call, formatted as decimal strings with four places (for example"0.0198", just under two cents). They include Bland’s margin. min, expected, and max are usage scenarios at 0.6x, 1x, and 1.6x of the assumed input and output volumes for a representative call; they are forecasts, not caps.
string
Deterministic estimate id, UUID-shaped. Identical for identical inputs. Pass it as
estimateId when publishing.string
The disposition that was priced.
number
The draft revision that was priced. Pass the same value as
expectedDraftRevision when publishing.array
One entry per value in the draft, in definition order.
Show per-value object
Show per-value object
string
The value’s id.
string
Human-readable label of how the value is produced and billed, for example
Judge · Automatic Intelligence, Structured extraction · Medium Intelligence, Variable extraction · High Intelligence, or Custom code · metered invocation. When two values share one judge invocation, the second reads Judge · shared invocation already included and is priced at zero. The one value that carries the once-per-call corrected transcript pass has + corrected transcript (once per call, shared) appended.object
{ "min", "expected", "max" } in USD per call for this value alone.object
{ "min", "expected", "max" } in USD per call, the sum across perValue.object
The fixed inputs behind the forecast.
Show assumptions object
Show assumptions object
number
Assumed call length in seconds, currently
254. Drives audio input volume and the corrected transcript charge.string
The draft’s
timing: immediate or within_24h.string
Always
usage_scenarios: min, expected, and max are 0.6x, 1x, and 1.6x of the assumed token volumes.object
How
custom_code values are billed. billingPolicy is monthly_free_tier (metered at list price after a free monthly allowance) or enterprise_included (included, quoted at zero). monthlyFreeInvocations is the allowance, currently 1000. listPriceUsdPerInvocation is the list price as a decimal string, currently "0.0010". freeTierScope is always organization. Under monthly_free_tier a code value’s min is 0.0000 and its expected and max equal the list price.string
Version tag of the pricing assumptions, currently
v3-intelligence-routing. Changes when the forecast model changes.null | array
null on success, or a list of error objects if the request failed.{
"data": {
"id": "541b9cf3-77fa-4f99-95de-356e656c5670",
"dispositionId": "16fc16fe-92af-4e8b-9459-28e10b05f287",
"draftRevision": 3,
"perValue": [
{
"valueId": "91b9a987-ee08-4018-a433-5a7a5d03dade",
"executionPath": "Judge · Automatic Intelligence",
"usdPerCall": { "min": "0.0121", "expected": "0.0198", "max": "0.0312" }
},
{
"valueId": "a1756910-0ff1-48be-8eb9-635c8bdfd533",
"executionPath": "Structured extraction · Medium Intelligence + corrected transcript (once per call, shared)",
"usdPerCall": { "min": "0.0018", "expected": "0.0031", "max": "0.0049" }
}
],
"totalUsdPerCall": { "min": "0.0139", "expected": "0.0229", "max": "0.0361" },
"assumptions": {
"averageDurationSeconds": 254,
"timing": "immediate",
"modelCostRange": "usage_scenarios",
"customCode": {
"billingPolicy": "monthly_free_tier",
"monthlyFreeInvocations": 1000,
"listPriceUsdPerInvocation": "0.0010",
"freeTierScope": "organization"
}
},
"quoteConfigVersion": "v3-intelligence-routing"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "SERVICE_UNAVAILABLE",
"message": "Disposition pricing is temporarily unavailable"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Disposition not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?