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

# Get Agent Composer Step Usage

> Get Agent Composer step-level usage data for a specific month.

This API returns daily usages of advance queries grouped by steps. The data is used for visualization purposes to show users which Agent Composer steps were executed and their associated costs and token consumption.

Note: The costs returned here are already included in the ACL_COST entry from the daily_usages table and should not be double-counted in billing.

Args: request: Request object containing year, month, and optional resource_id user_context: User context with tenant admin permissions

Returns: Agent Composer step usage data aggregated by step and date



## OpenAPI

````yaml api-reference/openapi.json get /billing/usages/acl
openapi: 3.1.0
info:
  title: Endpoints
  version: '1.0'
servers:
  - url: https://api.contextual.ai/v1
security:
  - BearerAuth: []
paths:
  /billing/usages/acl:
    get:
      tags:
        - /billing
      summary: Get Agent Composer Step Usage
      description: >-
        Get Agent Composer step-level usage data for a specific month.


        This API returns daily usages of advance queries grouped by steps. The
        data is used for visualization purposes to show users which Agent
        Composer steps were executed and their associated costs and token
        consumption.


        Note: The costs returned here are already included in the ACL_COST entry
        from the daily_usages table and should not be double-counted in billing.


        Args: request: Request object containing year, month, and optional
        resource_id user_context: User context with tenant admin permissions


        Returns: Agent Composer step usage data aggregated by step and date
      operationId: get_acl_step_usage_endpoint_billing_usages_acl_get
      parameters:
        - name: year
          in: query
          required: true
          schema:
            type: integer
            minimum: 2025
            title: Year
        - name: month
          in: query
          required: true
          schema:
            type: integer
            maximum: 12
            minimum: 1
            title: Month
        - name: resource_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Resource Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentComposerStepUsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentComposerStepUsageResponse:
      properties:
        usages:
          items:
            $ref: '#/components/schemas/AgentComposerStepUsage'
          type: array
          title: Usages
          description: List of Agent Composer step usages aggregated by step and date
      type: object
      required:
        - usages
      title: AgentComposerStepUsageResponse
      description: >-
        Response containing daily usages of advance queries grouped by steps.


        This API returns step-level breakdown of Agent Composer usage for
        visualization purposes. The costs in this response are already included
        in the ACL_COST entry from the daily_usages table and should not be
        double-counted.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentComposerStepUsage:
      properties:
        step_name:
          type: string
          title: Step Name
          description: Name of the pipeline step
        date:
          type: string
          title: Date
          description: Date in ISO format (YYYY-MM-DD)
        input_tokens:
          type: integer
          title: Input Tokens
          description: Total input tokens for this step
        output_tokens:
          type: integer
          title: Output Tokens
          description: Total output tokens for this step
        total_cost:
          type: number
          title: Total Cost
          description: Total cost in USD for this step
      type: object
      required:
        - step_name
        - date
        - input_tokens
        - output_tokens
        - total_cost
      title: AgentComposerStepUsage
      description: >-
        Single day's Agent Composer usage for a specific step.


        Represents aggregated usage data for a pipeline step on a specific date,
        summing across all models used by that step.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````