> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hacktron.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create cost estimation

> Estimate the credit cost of scanning one or more repositories before starting a scan.

A cost estimation resolves the repositories you plan to scan, detects applications within them, and returns a predicted credit cost. A `completed` or `partial` cost estimation with a positive `total_credits` value is required before calling [`POST /scans`](/api-reference/scans/create-scan).

Cost estimations run asynchronously. The `POST` returns a record in `pending` or `running` state; poll [`GET /cost-estimations/{id}`](/api-reference/cost-estimations/get-cost-estimation) until `status` reaches `completed`, `partial`, or `failed`.

<Info>**Scope required**: `write`</Info>

### Terminal statuses

| Status      | Meaning                                                                         |
| ----------- | ------------------------------------------------------------------------------- |
| `completed` | All repos were estimated successfully. `total_credits` is populated.            |
| `partial`   | Some repos completed, others failed. Check `repo_results[].status` for details. |
| `failed`    | The whole estimation failed. `error` contains a message.                        |

Once in a terminal state, an estimation is immutable. Pass its `id` as `cost_estimation_id` to [`POST /scans`](/api-reference/scans/create-scan) to start the scan. The scan must use repositories and branches that were included in the estimate.


## OpenAPI

````yaml POST /cost-estimations
openapi: 3.0.0
info:
  title: Hacktron REST API
  description: Public REST API for programmatic access to Hacktron
  version: '1.0'
  contact: {}
servers:
  - url: https://api.hacktron.ai/v1
security:
  - api-key: []
tags: []
paths:
  /cost-estimations:
    post:
      tags:
        - REST API - Cost Estimations
      summary: Create a cost estimation for one or more repos
      operationId: RestCostEstimationController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCostEstimationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostEstimationResponseDto'
components:
  schemas:
    CreateCostEstimationDto:
      type: object
      properties:
        name:
          type: string
          description: Friendly name for this estimation
        repos:
          type: array
          description: Repositories to estimate
          items:
            oneOf:
              - $ref: '#/components/schemas/ConnectedCostEstimationRepoDto'
              - $ref: '#/components/schemas/PublicCostEstimationRepoDto'
              - $ref: '#/components/schemas/UploadCostEstimationRepoDto'
            discriminator:
              propertyName: source
              mapping:
                connected:
                  $ref: '#/components/schemas/ConnectedCostEstimationRepoDto'
                public:
                  $ref: '#/components/schemas/PublicCostEstimationRepoDto'
                upload:
                  $ref: '#/components/schemas/UploadCostEstimationRepoDto'
      required:
        - repos
    CostEstimationResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Estimation UUID
          example: 123e4567-e89b-12d3-a456-426614174000
        organization_id:
          type: string
          description: Organization UUID
          example: f336d0bc-b841-465b-8045-024475c079dd
        user_id:
          type: string
          description: User UUID
          example: f336d0bc-b841-465b-8045-024475c079dd
        name:
          type: string
          description: Friendly name for this estimation
        task_id:
          type: string
          description: Task identifier
          example: cost_est_owner-repo_12345
        status:
          type: string
          description: Estimation status
          enum:
            - pending
            - running
            - completed
            - partial
            - failed
          example: completed
        repos:
          description: Input repositories
          type: array
          items:
            $ref: '#/components/schemas/RepoInputResponseDto'
        total_credits:
          type: number
          description: Total estimated credits across all repos
          example: 8000
        repo_results:
          description: Per-repo estimation results
          type: array
          items:
            $ref: '#/components/schemas/RepoResultResponseDto'
        error:
          type: string
          description: Error message
        triage_required:
          type: boolean
          description: >-
            Whether human triage is mandatory for a scan of this estimation
            (large app, above the predicted-cost threshold). The customer cannot
            opt out when true.
          example: false
        triage_fee_credits:
          type: number
          description: >-
            Triage fee in credits (a percentage of the scan base credits) added
            when triage is enabled
          example: 1600
        created_at:
          format: date-time
          type: string
          description: Timestamp when estimation was created
          example: '2026-03-10T12:00:00.000Z'
        updated_at:
          format: date-time
          type: string
          description: Timestamp when estimation was last updated
          example: '2026-03-10T12:05:00.000Z'
      required:
        - id
        - organization_id
        - user_id
        - task_id
        - status
        - repos
        - triage_required
        - triage_fee_credits
        - created_at
        - updated_at
    ConnectedCostEstimationRepoDto:
      type: object
      properties:
        source:
          type: string
          description: Source type
          enum:
            - connected
          default: connected
        repo_url:
          type: string
          description: Repository URL
        branch:
          type: string
          description: Branch name
        github_installation_id:
          type: number
          description: >-
            GitHub App installation ID. Omitted for PAT-based connections (e.g.
            GitHub Enterprise), where the installation is resolved from repo_url
            and the organization instead.
      required:
        - source
        - repo_url
        - branch
    PublicCostEstimationRepoDto:
      type: object
      properties:
        source:
          type: string
          description: Source type
          enum:
            - public
        repo_url:
          type: string
          description: Repository URL
        branch:
          type: string
          description: Branch name
      required:
        - source
        - repo_url
        - branch
    UploadCostEstimationRepoDto:
      type: object
      properties:
        source:
          type: string
          description: Source type
          enum:
            - upload
        archive_id:
          type: string
          description: Scan archive ID
      required:
        - source
        - archive_id
    RepoInputResponseDto:
      type: object
      properties:
        source:
          type: string
          description: Source type
          enum:
            - connected
            - public
            - upload
        repo_url:
          type: string
          description: Repository URL
          example: https://github.com/owner/repo
        branch:
          type: string
          description: Branch name
          example: main
        commit_sha:
          type: string
          description: Resolved commit SHA
          example: abc123def456
        archive_id:
          type: string
          description: Archive ID (for upload sources)
    RepoResultResponseDto:
      type: object
      properties:
        repo_url:
          type: string
          description: Repository URL
          example: https://github.com/owner/repo
        branch:
          type: string
          description: Branch name
          example: main
        commit_sha:
          type: string
          description: Commit SHA
          example: abc123def456
        status:
          type: string
          description: Result status
          enum:
            - completed
            - failed
          example: completed
        from_cache:
          type: boolean
          description: Whether result was served from cache
          example: false
        applications:
          description: Detected applications
          type: array
          items:
            $ref: '#/components/schemas/RepoResultApplicationDto'
        credits:
          type: number
          description: Estimated credits for this repo
          example: 4000
        error:
          type: string
          description: Error message (when status is failed)
        failure_reason:
          type: string
          description: Structured failure reason
          enum:
            - unsupported_language
        unsupported_languages:
          description: Detected unsupported languages among the top languages
          type: array
          items:
            type: string
      required:
        - repo_url
        - status
        - from_cache
    RepoResultApplicationDto:
      type: object
      properties:
        app_name:
          type: string
          description: Application name
          example: backend-api
        app_root_path:
          type: string
          description: Application root path
          example: apps/api
        architecture:
          type: string
          description: Architecture description
          example: NestJS REST API with PostgreSQL
      required:
        - app_name
        - app_root_path
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-Api-Key

````