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

# Showback by tag over time

> Spend per value of one tag or virtual-tag key for each day, week or month of the period, with shared costs split by the key's split rules exactly as in the showback endpoint: each point's value total is its direct spend plus the shared spend it receives (negative on a shared pool). Points are daily by default; weeks start on Monday and months on the 1st, and the first and last points are cut to the period, so their start and end can be shorter than a full week or month. Every point of the period is returned, with no values when it has no spend. start is inclusive and end exclusive, as dates. Spend with no value for the key is reported as unallocated. Amounts are gross, in the reporting currency, and each point is rounded to the cent on its own, so the points of a value can add up to a few cents more or less than its showback total.



## OpenAPI

````yaml /api-reference/costgraph/openapi.json get /api/v1/tenant/cost/showback-series
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: operator
    x-group: Operator
  - 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/cost/showback-series:
    get:
      tags:
        - cost
      summary: Showback by tag over time
      description: >-
        Spend per value of one tag or virtual-tag key for each day, week or
        month of the period, with shared costs split by the key's split rules
        exactly as in the showback endpoint: each point's value total is its
        direct spend plus the shared spend it receives (negative on a shared
        pool). Points are daily by default; weeks start on Monday and months on
        the 1st, and the first and last points are cut to the period, so their
        start and end can be shorter than a full week or month. Every point of
        the period is returned, with no values when it has no spend. start is
        inclusive and end exclusive, as dates. Spend with no value for the key
        is reported as unallocated. Amounts are gross, in the reporting
        currency, and each point is rounded to the cent on its own, so the
        points of a value can add up to a few cents more or less than its
        showback total.
      parameters:
        - description: Tenant ID
          name: X-CostGraph-Tenant-ID
          in: header
          required: true
          schema:
            type: string
        - description: Tag or virtual-tag key to show back by
          name: tag_key
          in: query
          required: true
          schema:
            type: string
        - description: Length of each point; defaults to day
          name: granularity
          in: query
          schema:
            type: string
            enum:
              - day
              - week
              - month
        - description: >-
            Cost layer; defaults to billed. allocation splits Kubernetes
            clusters into namespaces and workloads; database splits connected
            PostgreSQL instances into their databases and roles; layers are
            never mixed
          name: layer
          in: query
          schema:
            type: string
            enum:
              - billed
              - allocation
              - database
        - 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: >-
            ISO 4217 code to express every amount in; defaults to the currency
            most of the period's spend was billed in
          name: reporting_currency
          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.ShowbackSeries'
        '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.ShowbackSeries:
      type: object
      properties:
        basis:
          type: string
        granularity:
          type: string
        layer:
          type: string
        points:
          type: array
          items:
            $ref: '#/components/schemas/cost.ShowbackSeriesPoint'
        reportingCurrency:
          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.ShowbackSeriesPoint:
      type: object
      properties:
        end:
          type: string
        start:
          type: string
        total:
          type: number
          x-semantic: costAmount
        unallocated:
          type: number
          x-semantic: costAmount
        values:
          type: array
          items:
            $ref: '#/components/schemas/cost.ShowbackSeriesValue'
    cost.ShowbackSeriesValue:
      type: object
      properties:
        total:
          type: number
          x-semantic: costAmount
        value:
          type: string
  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.