---
title: "Submit AI tool usage report"
method: POST
path: "/ingest/ai-usage"
tags: ["Additional AI integrations"]
---

# Submit AI tool usage report

`POST /ingest/ai-usage`

Submit daily usage metrics for an external AI tool. Each request
can include data for multiple users and dates. Metrics are upserted
based on the combination of (aiService, user email, date).

The API token must have the `aiUsage` scope enabled.

## Request body

- AiUsageReport
  - `aiService` string, required — AI tool identifier (e.g. `Kiro`). Alphanumeric, preferably PascalCase. Created automatically if new. Visible in reports.
  - `data` AiUsageReportUser[], required — List of user usage records.
    - `email` string, email, required — User's (company) email address.
    - `date` string, date, required — Reporting date in ISO 8601 format (YYYY-MM-DD).
    - `is_enabled` boolean, required — Whether the user had a license or access to the AI tool during this day.
    - `is_active` boolean, required — Whether the user sent at least one message or accepted at least one suggestion from the AI tool.
    - `subscription_tier` string — Subscription tier (e.g. `free`, `pro`, `enterprise`).
    - `messages_count` integer — Total messages sent during the day.
    - `conversations_count` integer — Total conversations started during the day.
    - `spend_currency` string — ISO 4217 currency code (e.g. `USD`, `EUR`).
    - `subscription_spend_minor` integer — Subscription credits used during the day, in minor units (e.g. $10.00 = 1000).
    - `extra_usage_allowed` boolean — Whether extra usage beyond the subscription is permitted.
    - `extra_usage_limit_minor` integer — Extra usage limit, in minor units (e.g. $10.00 = 1000).
    - `extra_usage_spend_minor` integer — Extra usage credits used during the day, in minor units (e.g. $10.00 = 1000).
    - `breakdowns` AiUsageReportBreakdown[] — Usage broken down by any combination of dimensions. Each entry specifies one or more dimension keys (model, client, programming_language) together with the metrics for that slice. At least one dimension key is required per entry.
      - `model` string — Model identifier.
      - `client` string — Client application (e.g. web, ide, cli).
      - `programming_language` string — Language in use during the interaction.
      - `messages_count` integer — Messages in this slice.
      - `conversations_count` integer — Conversations in this slice.
      - `tokens_input` integer — Input tokens in this slice.
      - `tokens_output` integer — Output tokens in this slice.
      - `cache_read_tokens` integer — Cache read tokens in this slice.
      - `cache_creation_tokens` integer — Cache creation tokens in this slice.

## Response `200`

Report accepted successfully.

- object

## Other responses

- `400` — Validation error.
- `401` — Missing or invalid API token.
- `403` — Token lacks aiUsage scope.

---

[API](https://skmtc.net/swarmia/apis/swarmia-rest-api.md) · [All operations](https://skmtc.net/swarmia/apis/swarmia-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/swarmia/swarmia-rest-api/revisions/68d401c79425/schema)