--- title: Get Usage Detail Report keywords: - get usage detail report - get - usage - detail - report - forge - project groups --- # Get Usage Detail Report Break one month of an organization's spend down by model, API key, priority, Flowplate workflow, person, department, assistant, usage origin, Forge project group and partner share, with the month's daily totals. Its Forge spend (cloud servers and the git impact assessment) is also broken down by Forge project group in `by_forge_project_group`, so the usage page can show what was spent inside each group. A group carries the organization it bills to; see [List project groups](../forge-compute/list-project-groups.md). Authenticate with an API key (`X-API-Key`) or a Bearer token. The caller must be an active member of the organization and hold the `view_billing` capability. Every figure is money in CHF. No request, token, synapse or neuron count and no cost per request is returned. Each row carries its amount and its share of the month. {% api-container %} {% api-content %} {% endpoint method="GET" path="https://api.aitronos.com/v1/analytics/usage/detail/{org_id}" /%} #### Path Parameters **`org_id`** string required The organization ID. #### Query Parameters **`year`** integer optional The year (2020-2035). Default: the current year. **`month`** integer optional The month (1-12). Default: the current month, also when only `year` is sent. A month after the current one is `422` (`Cannot query future periods`). ## Returns The month's report. Every breakdown lists its rows most expensive first, and each row's `cost_share_percent` is its share of `period.total_cost_chf`, rounded to two decimals. ### Response Fields **`organization_id`** string The organization ID. **`period`** object The month: `total_cost_chf` (its whole spend, CHF), `start_date` and `end_date` (its first and last day, `YYYY-MM-DD`; the last day also while the month is running) and `currency` (`CHF`). **`by_model`** array of object `model` (the model key, or a category label for usage with no model of its own, as in [Get model ranking](../analytics/usage/model-ranking.md)), `total_cost_chf`, `cost_share_percent`. The rows add up to the month's spend. **`by_api_key`** array of object `api_key_id` (`bearer_token` for spend made signed in as a person), `api_key_name` (the key's name; `Bearer Token` on the `bearer_token` row; `Unknown Key` for a key that no longer exists), `total_cost_chf`, `cost_share_percent`. **`by_priority`** array of object `priority` (`low`, `default`, `high`, `fast`, `fw_priority` or `fw_fast`; the last three are serving-path premiums), `total_cost_chf`, `cost_share_percent`. **`by_flowplate`** array of object Only the spend made in Flowplate: `flow_id`, `node_type` and `source` (`node`, `playground`, `api` or `component`), each `null` when unknown, `total_cost_chf`, `cost_share_percent`. **`by_user`** array of object `user_id`, `first_name`, `last_name`, `email`, `total_cost_chf`, `cost_share_percent`. All four person fields are `null` on the row holding the spend made with an API key and no person. **`by_department`** array of object `department_id`, `department_name`, `total_cost_chf`, `cost_share_percent`. A department is charged for its current members, and a person in two departments is charged in full to each, so the rows can overlap and their shares add up to more than 100. Spend by people in no department, and API-key spend without a person, is in no row. **`by_department_reconciliation`** object How the department rows relate to the month's spend: - `is_partition`: always `false`; the rows do not partition the organization. - `sum_of_rows_chf`: the sum of every `by_department` row, overlap included, in CHF. - `organization_total_chf`: the month's spend, in CHF. - `multi_department_overlap_chf`: `sum_of_rows_chf` minus `organization_total_chf`, never below 0. Spend in no department lowers it, so it equals the spend counted twice only when all spend is in some department. **`by_assistant`** array of object Only the spend made through an assistant: `assistant_id`, `assistant_name` (`null` when the assistant no longer exists), `total_cost_chf`, `cost_share_percent`. **`by_source`** array of object Only the spend with a usage origin: `source` (the product it came from, e.g. `ticketing`), `feature` (e.g. `ai-field`), each `null` when unknown, `total_cost_chf`, `cost_share_percent`. **`by_forge_project_group`** array of object The organization's Forge spend in the period (Forge cloud servers and the [git impact assessment](../forge/assess-git-impact.md)) by Forge [project group](../forge-compute/list-project-groups.md): one row per group, most expensive first, then one row with `project_group_id: null` for Forge spend made outside any group (including spend from before the group existed). The rows cover the same period as the rest of the report and add up to the organization's Forge spend in it. Empty when the organization had no Forge spend in the period. Each row: - **`project_group_id`** string or `null`: the group's id (`fpgrp_` followed by 32 hex characters); `null` on the row for Forge spend outside any group. - **`name`** string: the group's name as it is now. A group deleted in Forge keeps its name here; `Not in a project group` on the `null` row; `Removed project group` when the group's record no longer exists. - **`owner_user_id`** string or `null`: whose group it is (project groups are personal); `null` on the `null` row and for a removed group. - **`owner_name`** string or `null`: the owner's name, else their email; `null` when unknown. - **`total_cost_chf`** number: the group's Forge spend, in CHF. - **`cost_label`** string: the cost to show, e.g. `CHF 12.40`. - **`cost_share_percent`** number: share of the organization's total cost in the period (all usage, not only Forge), rounded to two decimals. **`by_partner_share`** array of object The spend this organization paid through shares of partner organizations, most expensive first. It is also inside every other breakdown, never deducted from them, and empty for an organization that only provides shares: the organization that uses a share pays for it. Each row: - **`partner_share_id`** string: the share (`ptshr_`) the usage went through. - **`connection_id`**, **`partner_organization_id`**, **`partner_organization_name`** string or `null`: the partner connection and the organization that shared the resource; `null` when the share no longer exists, its spend still listed under its id. - **`resource_type`** string or `null`: the shared resource's type, e.g. `workflow`. - **`cost_chf`** string: the amount in CHF, as a decimal string (e.g. `"8.2150"`), not a number. - **`distinct_users`** integer: how many people's usage went through the share. - **`has_unverified_events`** boolean: `true` when some of this spend was written without its paying organization being cross-checked. **`daily_breakdown`** array of object One row per calendar day of the month, oldest first: `date` (`YYYY-MM-DD`), `total_cost_chf` and `has_data` (`false` on a day without any usage, whose `total_cost_chf` is `0`). The example shows the first seven of September's 30 days. **`generated_at`** string When the report was made (ISO 8601). {% /api-content %} {% api-examples %} {% code-group mode="dropdown" %} ```bash curl "https://api.aitronos.com/v1/analytics/usage/detail/org_abc123?year=2026&month=9" \ -H "X-API-Key: $FREDDY_API_KEY" ``` ```python import os import requests api_key = os.environ["FREDDY_API_KEY"] org_id = "org_abc123" response = requests.get( f"https://api.aitronos.com/v1/analytics/usage/detail/{org_id}", params={"year": 2026, "month": 9}, headers={"X-API-Key": api_key}, ) report = response.json() print(f"September: {report['period']['total_cost_chf']} CHF") for row in report["by_model"]: print(f"{row['model']}: {row['total_cost_chf']} CHF ({row['cost_share_percent']}%)") ``` ```javascript const response = await fetch( "https://api.aitronos.com/v1/analytics/usage/detail/org_abc123?year=2026&month=9", { headers: { "X-API-Key": process.env.FREDDY_API_KEY } } ); const report = await response.json(); console.log(`September: ${report.period.total_cost_chf} CHF`); for (const row of report.by_model) { console.log(`${row.model}: ${row.total_cost_chf} CHF (${row.cost_share_percent}%)`); } ``` {% /code-group %} **Response:** {% tabs %} {% tab label="200 OK" %} ```json { "organization_id": "org_abc123", "period": { "total_cost_chf": 148.6, "start_date": "2026-09-01", "end_date": "2026-09-30", "currency": "CHF" }, "by_model": [ { "model": "ftg-4", "total_cost_chf": 57.42, "cost_share_percent": 38.64 }, { "model": "ftg-3.0", "total_cost_chf": 41.88, "cost_share_percent": 28.18 }, { "model": "ftg-3.0-speed", "total_cost_chf": 19.65, "cost_share_percent": 13.22 }, { "model": "Forge cloud compute", "total_cost_chf": 14.89, "cost_share_percent": 10.02 }, { "model": "Web Scraping", "total_cost_chf": 9.41, "cost_share_percent": 6.33 }, { "model": "Meeting Buddy", "total_cost_chf": 4.93, "cost_share_percent": 3.32 }, { "model": "Embedding Model", "total_cost_chf": 0.42, "cost_share_percent": 0.28 } ], "by_api_key": [ { "api_key_id": "bearer_token", "api_key_name": "Bearer Token", "total_cost_chf": 122.54, "cost_share_percent": 82.46 }, { "api_key_id": "ak_5d2e8f1a3b7c4e9d8f6a0b2c4e1d3f57", "api_key_name": "Website chat", "total_cost_chf": 26.06, "cost_share_percent": 17.54 } ], "by_priority": [ { "priority": "default", "total_cost_chf": 139.25, "cost_share_percent": 93.71 }, { "priority": "high", "total_cost_chf": 9.35, "cost_share_percent": 6.29 } ], "by_flowplate": [ { "flow_id": "3b1f7c2a-9e4d-4a8b-b6c5-1d2e3f4a5b6c", "node_type": "Agent", "source": "node", "total_cost_chf": 6.84, "cost_share_percent": 4.6 } ], "by_user": [ { "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7", "first_name": "Dana", "last_name": "Keller", "email": "dana.keller@example.com", "total_cost_chf": 61.42, "cost_share_percent": 41.33 }, { "user_id": "usr_2b8e4d1f6a9c4e3b8d7f0a5c2e9b1d46", "first_name": "Luca", "last_name": "Brunner", "email": "luca.brunner@example.com", "total_cost_chf": 38.17, "cost_share_percent": 25.69 }, { "user_id": null, "first_name": null, "last_name": null, "email": null, "total_cost_chf": 26.06, "cost_share_percent": 17.54 }, { "user_id": "usr_9c1e5a3d7b2f4c8e9a6d0b4f1e3c7a25", "first_name": "Mia", "last_name": "Schneider", "email": "mia.schneider@example.com", "total_cost_chf": 22.95, "cost_share_percent": 15.44 } ], "by_department": [ { "department_id": "dept_fa969f37b5694e5285fc90bbdc2bc451", "department_name": "Sales", "total_cost_chf": 99.59, "cost_share_percent": 67.02 }, { "department_id": "dept_3f181fb896524f979a7a944f30910045", "department_name": "Engineering", "total_cost_chf": 84.37, "cost_share_percent": 56.78 } ], "by_department_reconciliation": { "is_partition": false, "sum_of_rows_chf": 183.96, "organization_total_chf": 148.6, "multi_department_overlap_chf": 35.36 }, "by_assistant": [ { "assistant_id": "asst_8a2c4e6f1b3d5a7c9e0f2b4d6a8c1e3f", "assistant_name": "Support Assistant", "total_cost_chf": 44.9, "cost_share_percent": 30.22 } ], "by_source": [ { "source": "ticketing", "feature": "ai-field", "total_cost_chf": 3.18, "cost_share_percent": 2.14 } ], "by_forge_project_group": [ { "project_group_id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "name": "Clients", "owner_user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7", "owner_name": "Dana Keller", "total_cost_chf": 12.4, "cost_label": "CHF 12.40", "cost_share_percent": 8.34 }, { "project_group_id": null, "name": "Not in a project group", "owner_user_id": null, "owner_name": null, "total_cost_chf": 2.49, "cost_label": "CHF 2.49", "cost_share_percent": 1.68 } ], "by_partner_share": [ { "partner_share_id": "ptshr_6c3e9a1f2b4d4e7a8c0f1b3d5e7a9c2e", "connection_id": "ptcon_1a3c5e7f9b2d4f6a8c0e2b4d6f8a1c3e", "partner_organization_id": "org_5e7a9c1b3d4f4a6c8e0b2d4f6a8c1e3b", "partner_organization_name": "Alpine Partners AG", "resource_type": "workflow", "cost_chf": "8.2150", "distinct_users": 3, "has_unverified_events": false } ], "daily_breakdown": [ { "date": "2026-09-01", "total_cost_chf": 6.31, "has_data": true }, { "date": "2026-09-02", "total_cost_chf": 7.02, "has_data": true }, { "date": "2026-09-03", "total_cost_chf": 6.88, "has_data": true }, { "date": "2026-09-04", "total_cost_chf": 5.47, "has_data": true }, { "date": "2026-09-05", "total_cost_chf": 0.0, "has_data": false }, { "date": "2026-09-06", "total_cost_chf": 0.0, "has_data": false }, { "date": "2026-09-07", "total_cost_chf": 7.15, "has_data": true } ], "generated_at": "2026-10-14T09:30:00.000000+00:00" } ``` {% /tab %} {% tab label="401 Unauthorized" %} ```json { "success": false, "error": { "code": "AUTHENTICATION_REQUIRED", "message": "Please sign in to continue.", "system_message": "Authentication required", "type": "authentication_error", "status": 401, "details": {}, "trace_id": "419a0186-9ee7-5ec2-9b54-de4444763064", "timestamp": "2026-10-14T09:30:00.000000Z" } } ``` {% /tab %} {% tab label="403 Forbidden" %} ```json { "success": false, "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You don't have permission to perform this action.", "system_message": "Missing required capability: view_billing", "type": "authorization_error", "status": 403, "details": { "required_capability": "view_billing", "user_id": "usr_bbb11deda760440cbde6c6db3fa8231f" }, "trace_id": "31bb888d-bb51-59b0-823b-1348725adc71", "timestamp": "2026-10-14T09:30:00.000000Z" } } ``` {% /tab %} {% tab label="422 Unprocessable Entity" %} ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Input should be less than or equal to 12", "system_message": "Request validation failed", "type": "validation_error", "status": 422, "details": { "fields": [ { "field": "query.month", "message": "Input should be less than or equal to 12", "type": "less_than_equal" } ] }, "trace_id": "6d9407dd-1a0a-5282-9f79-f62aede8c8dd", "timestamp": "2026-10-14T09:30:00.000000Z" } } ``` {% /tab %} {% tab label="422 Unprocessable Entity (future month)" %} ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Please check your input and try again.", "system_message": "Cannot query future periods", "type": "validation_error", "status": 422, "details": { "year": 2026, "month": 11 }, "trace_id": "91685ac7-1bf9-59e0-a582-eebd90574df9", "timestamp": "2026-10-14T09:30:00.000000Z" } } ``` {% /tab %} {% tab label="500 Server Error" %} ```json { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong. Please try again later.", "system_message": "An unexpected error occurred", "type": "server_error", "status": 500, "details": {}, "trace_id": "3c156968-0b9b-54bd-a759-77ad1b4be698", "timestamp": "2026-10-14T09:30:00.000000Z" } } ``` {% /tab %} {% /tabs %} {% /api-examples %} {% /api-container %} --- ## Related Resources - [List usage events](get-usage-events.md) - [Get model ranking](../analytics/usage/model-ranking.md) - [Get top users](../analytics/usage/top-users.md) - [Get department usage](../analytics/usage/department-usage.md) - [List project groups](../forge-compute/list-project-groups.md)