---
title: "Generate AI Report"
method: POST
path: "/ai/reports"
tags: ["AI"]
---

# Generate AI Report

`POST /ai/reports`

## Request

- Base URL: `https://api.crowdin.com/api/v2`
- URL: `https://api.crowdin.com/api/v2/ai/reports`
- Auth: none declared
- TypeScript: <https://skmtc.dev/crowdin/apis/crowdin-enterprise-api-v2/docs/ai/reports/post.ts> (a function with typed inputs; its response is checked against the schema)

**Required scopes:** `ai.provider` (Read only).

Generation is asynchronous and takes three requests. This one starts it and returns the report `identifier`. Then poll [Check AI Report Generation Status](#operation/api.ai.reports.get) until its `status` is `finished`; `progress` counts up to 100 meanwhile. Finally [Download AI Report](#operation/api.ai.reports.download.download) returns a short-lived `url`. Fetch that url to get the report file itself.

## Request body

- union
  - TokensUsageRawData: Every AI call of the period, one record each, with its tokens and cost, for auditing what a specific call spent, or for aggregating the raw numbers your own way. Use `costs-by-users` instead when you only need the totals per user
    - `type` 'tokens-usage-raw-data', required
    - `schema` object, required: The period, filters and file format every AI report accepts. Each report type composes this schema, so a field means the same thing whichever type you ask for
      - `dateFrom` string, date-time, required: Report date from in UTC, ISO 8601
      - `dateTo` string, date-time, required: Report date to in UTC, ISO 8601. Part of the period, so a whole day runs from `00:00:00` to `23:59:59`
      - `format` 'json' | 'csv': `csv` is a header row plus one data row per record; `json` wraps the same records and echoes the filters the report was built with
      - `projectIds` integer[]: Count only usage from these projects, ids via [List Projects](#operation/api.projects.getMany). Organization-level AI usage belongs to no project, so it drops out once this filter is set
      - `promptIds` integer[]: Count only usage made through these AI prompts, ids via [List AI Prompts](#operation/api.ai.prompts.getMany)
      - `userIds` integer[]: Count only usage by these users; by default everyone in the organization is included
      - `languageIds` string[]: Count only usage targeting these languages, ids via [List Supported Languages](#operation/api.languages.getMany). Usage without a target language drops out once this filter is set
  - CostsByUsers: AI spend per user for a period, already summed up: for billing AI usage back to a team, watching who nears an AI cost limit, or pulling the AI Usage page figures into your own dashboard. Use `tokens-usage-raw-data` instead when you need every individual AI call rather than per-user totals
    - `type` 'costs-by-users', required
    - `schema` AiReportBase, required: The period, filters and file format every AI report accepts. Each report type composes this schema, so a field means the same thing whichever type you ask for
      - `dateFrom` string, date-time, required: Report date from in UTC, ISO 8601
      - `dateTo` string, date-time, required: Report date to in UTC, ISO 8601. Part of the period, so a whole day runs from `00:00:00` to `23:59:59`
      - `format` 'json' | 'csv': `csv` is a header row plus one data row per record; `json` wraps the same records and echoes the filters the report was built with
      - `projectIds` integer[]: Count only usage from these projects, ids via [List Projects](#operation/api.projects.getMany). Organization-level AI usage belongs to no project, so it drops out once this filter is set
      - `promptIds` integer[]: Count only usage made through these AI prompts, ids via [List AI Prompts](#operation/api.ai.prompts.getMany)
      - `userIds` integer[]: Count only usage by these users; by default everyone in the organization is included

## Response `201`

AI Report generation was successfully started

- AiReportResource: Base schema of resource container. Container is a wrapper object that contains payload in required `data` property and provides space for adding any other metadata.
  - `data` AiReportGenerate, required: Generate AI Report Response Model
    - `identifier` string
    - `status` string
    - `progress` integer: in percentages
    - `attributes` object
      - `format` string
      - `reportType` string
      - `schema` object
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `startedAt` string, date-time
    - `finishedAt` string, date-time
    - `eta` string

## Other responses

- `400`: Invalid Request Parameters
- `401`: Unauthorized
- `403`: Forbidden
- `404`: AI report with specified type was not found
- `405`: Method Not Allowed

---

[API](https://skmtc.dev/crowdin/apis/crowdin-enterprise-api-v2.md) - [All operations](https://skmtc.dev/crowdin/apis/crowdin-enterprise-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/crowdin/apis/crowdin-enterprise-api-v2/revisions/dc68744c5384?raw)