---
title: "Request an estimate"
url: "https://nexora.apim.eu/apis/cost-estimation/versions/26a287d6-a67c-4989-b0bd-79a9db45597a/operations/requestEstimate"
---

> Full API specification: https://nexora.apim.eu/apis/cost-estimation/versions/26a287d6-a67c-4989-b0bd-79a9db45597a.md

# Request an estimate

`POST` `/estimates`

Operation ID: `requestEstimate`

Starts a cost/ROI estimate. Either for an existing agent via `agent_id` or for freeform input via `characteristics` - for example during an initial scoping conversation, before an agent deployment record exists.

## Request body (required)

Content types: `application/json`

## Responses

- `201` - Estimate created
- `400` - The request doesn't match the schema
- `422` - Data basis too thin for an indication

## OpenAPI definition

```yaml
openapi: 3.0.3
info:
  title: Cost & ROI Estimation
  version: 1.0.0
servers:
  - url: https://api.nexora.example/v1
    description: Production
  - url: https://sandbox.api.nexora.example/v1
    description: Sandbox
paths:
  /estimates:
    post:
      tags:
        - Estimates
      summary: Request an estimate
      description: |
        Starts a cost/ROI estimate. Either for an existing agent via
        `agent_id` or for freeform input via `characteristics` - for example
        during an initial scoping conversation, before an agent deployment
        record exists.
      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
security:
  - apiKey: []
components:
  schemas:
    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"
    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
    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
    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
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          example: basis.comparables_count
        reason:
          type: string
          example: missing
  responses:
    ValidationError:
      description: The request doesn't match the schema
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: |
        Every call carries an API key in the `apikey` header. You generate the
        key in the Nexora AI portal under "My Apps"; it's shown exactly once.

        Each key has the scopes it's allowed to use attached to it. If one is
        missing, the API responds with `403` and `code: "scope_missing"`; the
        missing scope is in `details[].field`.
```