---
title: "Get Agent Composer Step Usage"
method: GET
path: "/billing/usages/acl"
tags: ["/billing"]
---

# Get Agent Composer Step Usage

`GET /billing/usages/acl`

## Request

- Base URL: `https://api.contextual.ai/v1`
- URL: `https://api.contextual.ai/v1/billing/usages/acl`
- Auth: HTTP bearer

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

## Query parameters

- `year` integer, required
- `month` integer, required
- `resource_id` string, uuid, nullable

## Response `200`

Successful Response

- AgentComposerStepUsageResponse: 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.
  - `usages` AgentComposerStepUsage[], required: List of Agent Composer step usages aggregated by step and date
    - `step_name` string, required: Name of the pipeline step
    - `date` string, required: Date in ISO format (YYYY-MM-DD)
    - `input_tokens` integer, required: Total input tokens for this step
    - `output_tokens` integer, required: Total output tokens for this step
    - `total_cost` number, required: Total cost in USD for this step

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `4abdda722de9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/contextualai/apis/endpoints/changes/billing/usages/acl/get.md)

---

[API](https://skmtc.dev/contextualai/apis/endpoints.md) - [All operations](https://skmtc.dev/contextualai/apis/endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/contextualai/apis/endpoints/revisions/4abdda722de9?raw)