> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/swarmia-apis/additional-ai-integrations.md).
# Additional AI Integrations
Submit usage data from additional AI tools. This allows AI tools to report their usage metrics to Swarmia for unified tracking.
## Submit AI tool usage report
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Swarmia REST API","version":"1.0"},"tags":[{"name":"Additional AI integrations","description":"Submit usage data from additional AI tools. This allows AI tools\nto report their usage metrics to Swarmia for unified tracking.\n"}],"servers":[{"url":"https://app.swarmia.com/api/v1"}],"security":[{"bearerToken":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","description":"API token passed as `Authorization: Bearer `.\nThe token must have the `entityQuery` scope enabled.\nTokens can be provisioned at https://app.swarmia.com/settings/api-tokens.\n"}},"schemas":{"AiUsageReport":{"type":"object","required":["aiService","data"],"properties":{"aiService":{"type":"string","pattern":"^[A-Za-z0-9]+$","description":"AI tool identifier (e.g. `Kiro`). Alphanumeric, preferably PascalCase.\nCreated automatically if new. Visible in reports.\n"},"data":{"type":"array","description":"List of user usage records.","items":{"$ref":"#/components/schemas/AiUsageReport_User"}}}},"AiUsageReport_User":{"type":"object","required":["email","date","is_enabled","is_active"],"properties":{"email":{"type":"string","format":"email","description":"User's (company) email address."},"date":{"type":"string","format":"date","description":"Reporting date in ISO 8601 format (YYYY-MM-DD)."},"is_enabled":{"type":"boolean","description":"Whether the user had a license or access to the AI tool during this day."},"is_active":{"type":"boolean","description":"Whether the user sent at least one message or accepted at least one suggestion from the AI tool."},"subscription_tier":{"type":"string","description":"Subscription tier (e.g. `free`, `pro`, `enterprise`)."},"messages_count":{"type":"integer","minimum":0,"description":"Total messages sent during the day."},"conversations_count":{"type":"integer","minimum":0,"description":"Total conversations started during the day."},"spend_currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code (e.g. `USD`, `EUR`)."},"subscription_spend_minor":{"type":"integer","minimum":0,"description":"Subscription credits used during the day, in minor units (e.g. $10.00 = 1000)."},"extra_usage_allowed":{"type":"boolean","description":"Whether extra usage beyond the subscription is permitted."},"extra_usage_limit_minor":{"type":"integer","minimum":0,"description":"Extra usage limit, in minor units (e.g. $10.00 = 1000)."},"extra_usage_spend_minor":{"type":"integer","minimum":0,"description":"Extra usage credits used during the day, in minor units (e.g. $10.00 = 1000)."},"breakdowns":{"type":"array","description":"Usage broken down by any combination of dimensions.\nEach entry specifies one or more dimension keys (model, client,\nprogramming_language) together with the metrics for that slice.\nAt least one dimension key is required per entry.\n","items":{"$ref":"#/components/schemas/AiUsageReport_Breakdown"}}}},"AiUsageReport_Breakdown":{"type":"object","description":"A single usage slice. Include whichever dimension keys apply;\nat least one of model, client, or programming_language is required.\n","properties":{"model":{"type":"string","description":"Model identifier."},"client":{"type":"string","description":"Client application (e.g. web, ide, cli)."},"programming_language":{"type":"string","description":"Language in use during the interaction."},"messages_count":{"type":"integer","minimum":0,"description":"Messages in this slice."},"conversations_count":{"type":"integer","minimum":0,"description":"Conversations in this slice."},"tokens_input":{"type":"integer","minimum":0,"description":"Input tokens in this slice."},"tokens_output":{"type":"integer","minimum":0,"description":"Output tokens in this slice."},"cache_read_tokens":{"type":"integer","minimum":0,"description":"Cache read tokens in this slice."},"cache_creation_tokens":{"type":"integer","minimum":0,"description":"Cache creation tokens in this slice."}}},"EntityReport_Error":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}},"paths":{"/ingest/ai-usage":{"post":{"tags":["Additional AI integrations"],"operationId":"postUsage","summary":"Submit AI tool usage report","description":"Submit daily usage metrics for an external AI tool. Each request\ncan include data for multiple users and dates. Metrics are upserted\nbased on the combination of (aiService, user email, date).\n\nThe API token must have the `aiUsage` scope enabled.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiUsageReport"}}}},"responses":{"200":{"description":"Report accepted successfully.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityReport_Error"}}}},"401":{"description":"Missing or invalid API token."},"403":{"description":"Token lacks aiUsage scope."}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.swarmia.com/settings/integrations/swarmia-apis/additional-ai-integrations.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.