---
title: "Cost & ROI Estimation"
url: "https://nexora.apim.eu/apis/cost-estimation/versions/26a287d6-a67c-4989-b0bd-79a9db45597a"
---

# Cost & ROI Estimation

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Cost & ROI Estimation","version":"1.0.0","description":"Produces an initial cost indication for an agent deployment - based on\ncomparable deployments across the org, the internal usage index and the\nagent's own characteristics.\n\nThe result is an **indication**, not a formal cost model prepared under a\ncertified FinOps methodology. Every response therefore carries a range\nand a note on the underlying data basis, so it stays clear in\nconversations with budget owners how reliable the figure is.\n","contact":{"name":"API Support - Nexora AI","email":"api-support@nexora.example"},"license":{"name":"For demonstration purposes only"}},"servers":[{"url":"https://api.nexora.example/v1","description":"Production"},{"url":"https://sandbox.api.nexora.example/v1","description":"Sandbox"}],"tags":[{"name":"Estimates"},{"name":"Comparables"},{"name":"Usage Index"}],"security":[{"apiKey":[]}],"paths":{"/estimates":{"post":{"tags":["Estimates"],"summary":"Request an estimate","description":"Starts a cost/ROI estimate. Either for an existing agent via\n`agent_id` or for freeform input via `characteristics` - for example\nduring an initial scoping conversation, before an agent deployment\nrecord exists.\n","operationId":"requestEstimate","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateRequest"},"examples":{"existingAgent":{"summary":"For an already-registered agent","value":{"agent_id":"agt_8f2c1a","reason":"production_rollout"}},"freeformInput":{"summary":"During initial scoping, without an agent record","value":{"reason":"initial_scoping","characteristics":{"category":"copilot","business_unit":"Customer Success","integration_count":6,"expected_monthly_requests":250000,"maturity":"stabilizing","deployment_tier":"pilot","has_rag":true,"has_tool_use":true,"has_human_in_loop":false}}}}}}},"responses":{"201":{"description":"Estimate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostEstimateResult"},"example":{"id":"est_3e18","reason":"production_rollout","estimated_monthly_cost_usd":6380,"range_usd":{"low":6020,"high":6740},"cost_per_1k_requests_usd":25.5,"confidence":"medium","basis":{"comparables_count":23,"period_months":12,"sample_scope":"business_unit"},"created_at":"2026-08-20T09:52:00Z"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"422":{"description":"Data basis too thin for an indication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"insufficient_data","message":"Too few comparable deployments are available for this business unit.","details":[{"field":"basis.comparables_count","reason":"below_minimum"}]}}}}}}},"/estimates/{estimateId}":{"parameters":[{"name":"estimateId","in":"path","required":true,"schema":{"type":"string","example":"est_3e18"}}],"get":{"tags":["Estimates"],"summary":"Retrieve an estimate","operationId":"getEstimate","responses":{"200":{"description":"Estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostEstimateResult"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/comparables":{"get":{"tags":["Comparables"],"summary":"List comparable deployments","description":"Anonymized deployments from across the org. Team names are rounded up\nto the business-unit level so no individual deployment can be traced\nback.\n","operationId":"listComparables","parameters":[{"name":"business_unit","in":"query","required":true,"schema":{"type":"string","example":"Customer Success"}},{"name":"category","in":"query","required":true,"schema":{"type":"string","enum":["copilot","autonomous-agent","workflow-agent","rag-assistant","voice-agent"]}},{"name":"integration_count","in":"query","description":"Reference size; matches are searched within a ±20 percent corridor.","schema":{"type":"number","format":"float","example":6}},{"name":"period_months","in":"query","schema":{"type":"integer","minimum":3,"maximum":36,"default":12}}],"responses":{"200":{"description":"Comparable deployments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Comparable"}},"stats":{"$ref":"#/components/schemas/Metrics"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"}}}},"/usage-index":{"get":{"tags":["Usage Index"],"summary":"Get usage index values","description":"Typical comparable request volume and cost for the category, based on aggregated internal usage data.","operationId":"getUsageIndex","parameters":[{"name":"business_unit","in":"query","required":true,"schema":{"type":"string","example":"Customer Success"}},{"name":"integration_count","in":"query","required":true,"schema":{"type":"number","format":"float","example":6}},{"name":"model_release_date","in":"query","schema":{"type":"string","format":"date","example":"2026-02-01"}}],"responses":{"200":{"description":"Usage index values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageIndexValue"},"example":{"business_unit":"Customer Success","as_of":"2025-01-01","cost_per_1k_requests_usd":{"low":18.4,"average":25.5,"high":34.6},"range_note":"Values apply to a typical mid-complexity deployment without adjustments."}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Nexora AI portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"basis.comparables_count"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Nexora AI APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string","example":"Too few comparable deployments are available for this business unit."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"EstimateReason":{"type":"string","enum":["initial_scoping","production_rollout","budget_planning","renewal","decommission"],"example":"production_rollout"},"Characteristics":{"type":"object","description":"Freeform agent description, used when no agent deployment record exists.","required":["category","business_unit","integration_count"],"properties":{"category":{"type":"string","enum":["copilot","autonomous-agent","workflow-agent","rag-assistant","voice-agent"]},"business_unit":{"type":"string","example":"Customer Success"},"integration_count":{"type":"number","format":"float","example":6},"tool_count":{"type":"number","format":"float","example":4},"expected_monthly_requests":{"type":"number","format":"float","example":250000},"model_release_date":{"type":"string","format":"date","example":"2026-02-01"},"maturity":{"type":"string","enum":["pilot","stabilizing","mature","legacy"]},"deployment_tier":{"type":"string","enum":["sandbox","pilot","production"]},"has_rag":{"type":"boolean","example":true},"has_tool_use":{"type":"boolean","example":true},"has_human_in_loop":{"type":"boolean","example":false}}},"EstimateRequest":{"type":"object","required":["reason"],"description":"Exactly one of `agent_id` or `characteristics` must be set.","properties":{"agent_id":{"type":"string","example":"agt_8f2c1a"},"reason":{"$ref":"#/components/schemas/EstimateReason"},"characteristics":{"$ref":"#/components/schemas/Characteristics"}}},"Range":{"type":"object","properties":{"low":{"type":"integer","example":6020},"high":{"type":"integer","example":6740}}},"EstimateBasis":{"type":"object","description":"What the indication was derived from.","properties":{"comparables_count":{"type":"integer","example":23},"period_months":{"type":"integer","example":12},"sample_scope":{"type":"string","enum":["team","business_unit","org_wide"],"example":"business_unit"}}},"CostEstimateResult":{"type":"object","properties":{"id":{"type":"string","example":"est_3e18"},"agent_id":{"type":"string","nullable":true,"example":"agt_8f2c1a"},"reason":{"$ref":"#/components/schemas/EstimateReason"},"estimated_monthly_cost_usd":{"type":"integer","example":6380},"range_usd":{"$ref":"#/components/schemas/Range"},"cost_per_1k_requests_usd":{"type":"number","format":"float","example":25.5},"confidence":{"type":"string","description":"How reliable the indication is.","enum":["low","medium","high"]},"basis":{"$ref":"#/components/schemas/EstimateBasis"},"created_at":{"type":"string","format":"date-time","example":"2026-08-20T09:52:00Z"}}},"Comparable":{"type":"object","properties":{"business_unit_rounded":{"type":"string","example":"Customer Success"},"integration_count":{"type":"number","format":"float","example":5},"tool_count":{"type":"number","format":"float","example":4},"model_release_date":{"type":"string","format":"date","example":"2026-01-15"},"monthly_cost_usd":{"type":"integer","example":6100},"cost_per_1k_requests_usd":{"type":"number","format":"float","example":24.8},"deployed_month":{"type":"string","example":"2026-03"}}},"Metrics":{"type":"object","properties":{"count":{"type":"integer","example":23},"median_cost_per_1k_requests_usd":{"type":"number","format":"float","example":25.1},"lower_quartile_cost_per_1k_requests_usd":{"type":"number","format":"float","example":21.4},"upper_quartile_cost_per_1k_requests_usd":{"type":"number","format":"float","example":28.9}}},"UsageIndexValue":{"type":"object","properties":{"business_unit":{"type":"string","example":"Customer Success"},"as_of":{"type":"string","format":"date","example":"2025-01-01"},"cost_per_1k_requests_usd":{"type":"object","properties":{"low":{"type":"number","format":"float","example":18.4},"average":{"type":"number","format":"float","example":25.5},"high":{"type":"number","format":"float","example":34.6}}},"range_note":{"type":"string","example":"Values apply to a typical mid-complexity deployment without adjustments."}}}}}}
```