---
title: "Retrieve usage information segmented by time period with tool-specific breakdowns"
method: GET
path: "/manage/api/usage"
tags: ["manage"]
---

# Retrieve usage information segmented by time period with tool-specific breakdowns

`GET /manage/api/usage`

## Query parameters

- `organization_id` string, required
- `segment_by` 'DAY' | 'HOUR', required — Time segment granularity for usage breakdown
- `start_time` string, date-time, required
- `end_time` string, date-time
- `model_versions` ModelVersion[]
- `tools` ToolType[]
- `api_key_ids` string[]
- `user_emails` string[]
- `source` 'API' | 'APP' — Filter usage by source - API for programmatic API usage, APP for web application usage

## Response `200`

Usage information retrieved successfully

- GetUsageInfoResponse
  - `usage_segments` UsageSegment[], required — List of usage segments with tool-specific breakdowns
    - `segment_start` string, date-time, required — Start time of the usage segment
    - `segment_end` string, date-time, required — End time of the usage segment
    - `tool_usage` ToolUsage[], required — Tool-specific usage breakdown within this segment
      - `full_tool_name` string, required — Name of the tool used
      - `amount` Price, required — Represents a price.
        - `currency_code` string, required — The ISO 4217 currency code for the price object.
        - `amount` number, required — The amount of the currency in the common denomination. For example, in USD this is cents.
      - `api_key_id` string — Base64 encoded API key ID (for API usage)
      - `user_email_address` string — User email address (for web app usage)
      - `tool_type` 'GENERATE' | 'REMIX' | 'EDIT' | 'UPSCALE' | 'DESCRIBE' | 'OTHER', required — Tool type for filtering usage information
      - `model_version` 'V_0_1' | 'V_0_2' | 'V_0_3' | 'V_1_1' | 'V_1_5' | 'V_2_1' | 'V_3_0' | 'V_3_1' | 'V_4_0' | 'V_4_D' | 'V_4_LAYOUT2IMAGE' | 'EXTERNAL_GOOGLE_VEO_3_0' | 'EXTERNAL_BYTEDANCE_SEEDANCE_1_0_PRO' | 'EXTERNAL_MINIMAX_HAILUO_02' | 'EXTERNAL_MODEL' | 'AUTO' — The model_version to use. - V_0_3: Model 1.0 - V_1_1: Model 1.1 - V_1_5: Model 2.0 - V_2_1: Model 2a - V_3_0: Model 3.0 March 26 - V_3_1: Model 3.0 Latest - V_4_0: Model 4.0 - V_4_D: Model 4.0 Layered Design (vector-text path; gated by the access_to_v4_experimental feature flag) - V_4_LAYOUT2IMAGE: Model 4.0 Layout to Image (HTML layout rasterized as IMAGE_TO_IMAGE conditioning; gated by the access_to_v4_experimental feature flag) - AUTO: Automatically select the best model version based on the request.

## Other responses

- `401` — Not authorized
- `403` — Not authorized

---

[API](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.net/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/versions/bcc2d45be91e/schema)