# Built In reports

Pre-built reports that surface metrics from Swarmia. Each report endpoint returns rows with a fixed set of metrics, a schema describing its properties, and an optional summary row that aggregates across all rows.

## Organization AI assistant overview

> Overview of AI assistant usage in the organization.

```json
{"openapi":"3.1.0","info":{"title":"Swarmia REST API","version":"1.0"},"tags":[{"name":"Built-in reports","description":"Pre-built reports that surface metrics from Swarmia. Each report\nendpoint returns rows with a fixed set of metrics, a schema\ndescribing its properties, and an optional summary row that\naggregates across all rows.\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 <token>`.\nThe token must have the `entityQuery` scope enabled.\nTokens can be provisioned at https://app.swarmia.com/settings/api-tokens.\n"}},"parameters":{"output":{"name":"output","in":"query","description":"Response format.","schema":{"type":"string","enum":["json","csv"],"default":"json"}}},"schemas":{"EntityReport_AiAdoptionUsersAndLicenses_Result":{"type":"object","required":["schema","rows"],"properties":{"schema":{"type":"object","description":"Describes each property in `rows`. Keys are property names,\nvalues carry things like a human-readable `title`, `description`, etc.\n","additionalProperties":{"$ref":"#/components/schemas/SchemaEntry"}},"summaryRow":{"description":"Aggregate across all rows in the response. Same shape as\neach row but without `_key`.\n","type":"object","required":["enabledAiUsers","activeAiUsers","enabledAiUserCount","activeAiUserCount","contributorCount","weeklyActiveAvg","enabledRate"],"properties":{"enabledAiUsers":{"type":"array","items":{"$ref":"#/components/schemas/EntityReference_Author"}},"activeAiUsers":{"type":"array","items":{"$ref":"#/components/schemas/EntityReference_Author"}},"enabledAiUserCount":{"type":"integer"},"activeAiUserCount":{"type":"integer"},"contributorCount":{"type":"integer"},"weeklyActiveAvg":{"type":["number","null"]},"enabledRate":{"type":["number","null"]}}},"rows":{"type":"array","items":{"type":"object","required":["_key","enabledAiUsers","activeAiUsers","enabledAiUserCount","activeAiUserCount","contributorCount","weeklyActiveAvg","enabledRate"],"properties":{"_key":{"$ref":"#/components/schemas/EntityReference_Team"},"enabledAiUsers":{"type":"array","description":"Authors with an AI assistant license during the period.","items":{"$ref":"#/components/schemas/EntityReference_Author"}},"activeAiUsers":{"type":"array","description":"Authors who actively used an AI assistant during the period. Empty array when none.","items":{"$ref":"#/components/schemas/EntityReference_Author"}},"enabledAiUserCount":{"type":"integer","description":"Count of licensed authors. `0` when no data."},"activeAiUserCount":{"type":"integer","description":"Count of active authors. `0` when no data."},"contributorCount":{"type":"integer","description":"Count of team members (scoped by `activeContributorsOnly`). `0` when no data."},"weeklyActiveAvg":{"type":["number","null"],"description":"Average weekly active users. `null` when incalculable (e.g. no snapshot data)."},"enabledRate":{"type":["number","null"],"description":"Percentage of members with a license (0–100). `null` when incalculable."}}}}}},"SchemaEntry":{"type":"object","required":["title","description"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"aggregate":{"type":"string","description":"The aggregation function used (e.g. `CountDistinct`, `ArrayAggDistinct`)."}}},"EntityReference_Author":{"type":"object","description":"Authors are the people or bots that can be attributed different kinds of work items (commits, pull requests, reviews). Authors can be linked to multiple identities across different systems (GitHub, Slack, Jira, etc.)","required":["type","id","name","email"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","const":"Author"},"name":{"type":["string","null"]},"email":{"type":["string","null"]}}},"EntityReference_Team":{"type":"object","description":"Teams represent your organization structure and are the owners of other entities like Issues and Pull requests.","required":["type","id","name"],"properties":{"type":{"type":"string","const":"Team"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"EntityReport_Error":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}},"paths":{"/reports/ai/adoption/users-and-licenses":{"get":{"tags":["Built-in reports"],"operationId":"getReportsAiAdoptionUsersAndLicenses","summary":"Organization AI assistant overview","description":"Overview of AI assistant usage in the organization.","parameters":[{"$ref":"#/components/parameters/output"},{"name":"timeframe.start","in":"query","required":true,"description":"Start of the reporting period (inclusive).","schema":{"type":"string","format":"date"}},{"name":"timeframe.end","in":"query","required":true,"description":"End of the reporting period (inclusive).","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","description":"IANA timezone used to interpret the date-only `timeframe.start`\nand `timeframe.end` values and for time bucketing. Defaults to `UTC`.\n","schema":{"type":"string","default":"UTC"}},{"name":"teamId","in":"query","description":"Comma-separated team UUIDs. Only these teams are included.\nUse either this or `parentTeamId`, not both. Omit both to\nreturn all teams.\n","schema":{"type":"string"}},{"name":"parentTeamId","in":"query","description":"Comma-separated parent-team UUIDs. Returns children of these\nteams. Use the literal value `null` (or an empty value) to\nselect only top-level teams (teams with no parent).\nUse either this or `teamId`, not both. Omit both to return\nall teams.\n","schema":{"type":"string"}},{"name":"activeContributorsOnly","in":"query","description":"When `true` (default), only count team members who opened at\nleast one PR during the time period. When `false`, count all\nteam members.\n","schema":{"type":"boolean","default":true}},{"name":"aiAssistants","in":"query","description":"Comma-separated list of AI assistants to include. Omit to include all.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityReport_AiAdoptionUsersAndLicenses_Result"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid or unknown parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityReport_Error"}}}},"401":{"description":"Missing or invalid API token."}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://help.swarmia.com/settings/integrations/swarmia-apis/built-in-reports.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.