> ## 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.

# Allocation coverage

> Share of gross spend (credits excluded) that a tag key assigns a value to, counting virtual-tag rules the same way the cost query does. Without tag_key any provider tag or virtual tag counts as allocated. Coverage is reported per billed currency because spend in different currencies is never summed, and for one cost layer at a time. With group_by it also lists the groups with the most unallocated spend.



## OpenAPI

````yaml /api-reference/costgraph/openapi.json get /api/v1/tenant/cost/allocation-coverage
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: cost
    x-group: Cost
  - name: gpus
    x-group: GPUs
  - name: graphai
    x-group: Graph AI
  - name: infracost
    x-group: Infracost
  - name: integrations
    x-group: Integrations
  - name: invitations
    x-group: Invitations
  - name: kubernetes-clusters
    x-group: Kubernetes clusters
  - name: marketplace
    x-group: Marketplace
  - 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: service-map
    x-group: Service map
  - name: settings
    x-group: Settings
  - name: sso
    x-group: Single sign-on
  - name: tenants
    x-group: Tenants
  - 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/cost/allocation-coverage:
    get:
      tags:
        - cost
      summary: Allocation coverage
      description: >-
        Share of gross spend (credits excluded) that a tag key assigns a value
        to, counting virtual-tag rules the same way the cost query does. Without
        tag_key any provider tag or virtual tag counts as allocated. Coverage is
        reported per billed currency because spend in different currencies is
        never summed, and for one cost layer at a time. With group_by it also
        lists the groups with the most unallocated spend.
      parameters:
        - description: Tenant ID
          name: X-CostGraph-Tenant-ID
          in: header
          required: true
          schema:
            type: string
        - description: Tag or virtual-tag key to measure; omit to count any tag
          name: tag_key
          in: query
          schema:
            type: string
        - description: Cost layer; defaults to billed
          name: layer
          in: query
          schema:
            type: string
            enum:
              - billed
              - allocation
        - description: >-
            One dimension to break unallocated spend down by; accepts any
            dimension the cost query group_by accepts
          name: group_by
          in: query
          schema:
            type: string
        - description: Maximum groups per currency; defaults to 100
          name: group_limit
          in: query
          schema:
            type: integer
        - description: Cost period; defaults to month_to_date
          name: period
          in: query
          schema:
            type: string
            enum:
              - month_to_date
              - last_7d
              - last_30d
              - calendar_month
              - custom
        - description: >-
            Closed calendar month in YYYY-MM format; required when
            period=calendar_month
          name: month
          in: query
          schema:
            type: string
        - description: Window start in RFC3339 format; required when period=custom
          name: start
          in: query
          schema:
            type: string
        - description: Window end in RFC3339 format; required when period=custom
          name: end
          in: query
          schema:
            type: string
        - description: >-
            Repeated key:value dimension filter, the same vocabulary as the cost
            query filter
          name: filter
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/responses.SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/cost.Coverage'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    responses.SuccessResponse:
      type: object
      required:
        - message
        - status
      properties:
        data: {}
        message:
          type: string
          example: some message
        status:
          type: string
          example: success
    cost.Coverage:
      type: object
      properties:
        byCurrency:
          type: array
          items:
            $ref: '#/components/schemas/cost.CoverageAmounts'
        groupBy:
          type: string
        groups:
          type: array
          items:
            $ref: '#/components/schemas/cost.CoverageGroup'
        layer:
          type: string
        tagKey:
          type: string
    responses.ErrorResponse:
      type: object
      required:
        - message
        - status
      properties:
        message:
          type: string
          example: some message
        status:
          type: string
          example: error
    cost.CoverageAmounts:
      type: object
      properties:
        allocated:
          type: number
          x-semantic: costAmount
        allocatedPct:
          type: number
          x-semantic: percentage
        currency:
          type: string
        total:
          type: number
          x-semantic: costAmount
        unallocated:
          type: number
          x-semantic: costAmount
    cost.CoverageGroup:
      type: object
      properties:
        allocated:
          type: number
          x-semantic: costAmount
        allocatedPct:
          type: number
          x-semantic: percentage
        currency:
          type: string
        key:
          type: string
        total:
          type: number
          x-semantic: costAmount
        unallocated:
          type: number
          x-semantic: costAmount
  securitySchemes:
    BearerAuth:
      description: Enter "Bearer {token}"
      type: apiKey
      name: Authorization
      in: header

````

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