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

# Start a sandbox

> Starts a sandbox on one of the team's connected sandbox accounts that CostGraph can run. With no provider, CostGraph AutoPilot orders the connected providers for the size and policy, as the route endpoint does, and when a provider cannot start the sandbox the next one is tried; every failed attempt is recorded. provider limits the start to that connected provider. Send the size as size_class (xs, sm, md, lg, xl or 2xl), or as vcpus and memory_mib; with neither, each provider starts its own default size. policy (cheapest, balanced or fastest) overrides the team's policy for this sandbox. metadata holds at most 16 string tags, which are passed to the provider as labels, and metadata.run, the run key, also sets the provider's run label, and a new run key is generated when it is absent; keys starting with costgraph.ai/ are reserved and dropped. lifecycle.timeout_ms asks the provider to end the sandbox after that many milliseconds. The sandbox is recorded as started with its price per hour, so it shows in the sandbox list and in AutoPilot savings. routed_from names the provider tried first when the sandbox started elsewhere. When every provider tried refuses the sandbox, for its size, credits, plan or key, nothing was started and the answer is 422 with what to change; 502 means a provider may still have started one.



## OpenAPI

````yaml /api-reference/costgraph/openapi.json post /api/v1/tenant/sandboxes
openapi: 3.0.0
info:
  description: Read and manage your CostGraph organization, spend, alerts, and settings.
  title: CostGraph API
  contact: {}
  version: '1.0'
servers:
  - url: https://api.costgraph.ai
security: []
tags:
  - name: ai
    x-group: AI
  - name: ai-serving
    x-group: AI serving
  - name: anomalies
    x-group: Anomalies
  - name: auth
    x-group: Auth
  - name: billing
    x-group: Billing
  - name: billing-export
    x-group: Billing export
  - name: budgets
    x-group: Budgets
  - name: ci
    x-group: CI
  - name: compute-recommendations
    x-group: Compute recommendations
  - name: config
    x-group: Config
  - name: context-graph
    x-group: Context graph
  - name: cost
    x-group: Cost
  - name: gpus
    x-group: GPUs
  - name: graphai
    x-group: Graph AI
  - name: integrations
    x-group: Integrations
  - name: invitations
    x-group: Invitations
  - name: kubernetes-clusters
    x-group: Kubernetes clusters
  - name: marketplace
    x-group: Marketplace
  - name: network
    x-group: Network
  - name: network-requests
    x-group: Network requests
  - name: notifications
    x-group: Notifications
  - name: oauth
    x-group: OAuth
  - name: oauth-clients
    x-group: OAuth clients
  - name: opencost
    x-group: OpenCost
  - name: organization
    x-group: Audit log
  - name: organizations
    x-group: Organizations
  - name: placement-alternatives
    x-group: Placement alternatives
  - name: reports
    x-group: Reports
  - name: sandboxes
    x-group: Sandboxes
  - name: settings
    x-group: Settings
  - name: sso
    x-group: Single sign-on
  - name: tenants
    x-group: Tenants
  - name: ticketing
    x-group: Ticketing
  - name: user
    x-group: Users
  - name: virtual-machines
    x-group: Virtual machines
  - name: virtual-tags
    x-group: Virtual tags
  - name: workflows
    x-group: Workflows
paths:
  /api/v1/tenant/sandboxes:
    post:
      tags:
        - sandboxes
      summary: Start a sandbox
      description: >-
        Starts a sandbox on one of the team's connected sandbox accounts that
        CostGraph can run. With no provider, CostGraph AutoPilot orders the
        connected providers for the size and policy, as the route endpoint does,
        and when a provider cannot start the sandbox the next one is tried;
        every failed attempt is recorded. provider limits the start to that
        connected provider. Send the size as size_class (xs, sm, md, lg, xl or
        2xl), or as vcpus and memory_mib; with neither, each provider starts its
        own default size. policy (cheapest, balanced or fastest) overrides the
        team's policy for this sandbox. metadata holds at most 16 string tags,
        which are passed to the provider as labels, and metadata.run, the run
        key, also sets the provider's run label, and a new run key is generated
        when it is absent; keys starting with costgraph.ai/ are reserved and
        dropped. lifecycle.timeout_ms asks the provider to end the sandbox after
        that many milliseconds. The sandbox is recorded as started with its
        price per hour, so it shows in the sandbox list and in AutoPilot
        savings. routed_from names the provider tried first when the sandbox
        started elsewhere. When every provider tried refuses the sandbox, for
        its size, credits, plan or key, nothing was started and the answer is
        422 with what to change; 502 means a provider may still have started
        one.
      parameters:
        - description: Tenant ID
          name: X-CostGraph-Tenant-ID
          in: header
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sandboxapi.CreateRequest'
        description: Provider, size, policy and tags
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/responses.SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/sandboxapi.Created'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    sandboxapi.CreateRequest:
      type: object
      properties:
        lifecycle:
          $ref: '#/components/schemas/sandboxapi.Lifecycle'
        memory_mib:
          type: integer
          maximum: 4194304
          minimum: 1
        metadata:
          type: object
          additionalProperties:
            type: string
        policy:
          type: string
          enum:
            - ''
            - cheapest
            - balanced
            - fastest
        provider:
          type: string
          maxLength: 64
        size_class:
          type: string
          enum:
            - ''
            - xs
            - sm
            - md
            - lg
            - xl
            - 2xl
        vcpus:
          type: integer
          maximum: 1024
          minimum: 1
    responses.SuccessResponse:
      type: object
      required:
        - message
        - status
      properties:
        data: {}
        message:
          type: string
          example: some message
        status:
          type: string
          example: success
    sandboxapi.Created:
      type: object
      required:
        - provider
        - sandbox_id
        - started_at
      properties:
        decision_id:
          type: string
        price_per_hour:
          type: number
          x-semantic: costAmount
          nullable: true
        provider:
          type: string
        routed_from:
          type: string
        sandbox_id:
          type: string
        started_at:
          type: string
    responses.ErrorResponse:
      type: object
      required:
        - message
        - status
      properties:
        message:
          type: string
          example: some message
        status:
          type: string
          example: error
    sandboxapi.Lifecycle:
      type: object
      properties:
        timeout_ms:
          type: integer
          maximum: 86400000
          minimum: 1000
  securitySchemes:
    ApiKeyAuth:
      description: API key for machine-to-machine authentication
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.