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.
Every built-in report request must include a revision query parameter. Revisions let us evolve report behavior without breaking existing integrations — pin a numeric revision for stable output, or pass latest to follow the newest revision for that report.
Overview of pull request metrics per team, mirroring the Code metrics — Overview report in the app. Returns one row per matched team plus a summaryRow aggregating across all of them.
Durations (cycleTime, timeToFirstReview, mergeTime) are in seconds. reviewRate is a percentage (0–100). The numeric aggregate parameter controls how the duration and batch-size metrics are aggregated.
When excludeWeekends is omitted, cycleTime and mergeTime follow the organization's Metric calculation setting. Pass true or false to override that setting for this request. timeToFirstReview always excludes weekends.
This organization-dependent default applies to revisions 1 and 2. Requests that omit excludeWeekends can therefore return different durations after an organization admin changes the setting, even when the request uses a fixed revision.
Supported revisions: 1, 2 (latest is equivalent to 2). Revision 2 added the teamFte and mergedPrsByFte columns and treats teamId/parentTeamId as comma-separated lists. In revision 1, supplying teamId returns that team's child teams only (the team itself is excluded from rows but still counted in summaryRow).
API token passed as Authorization: Bearer <token>.
The token must have the scope required by the endpoint.
Tokens can be provisioned at https://app.swarmia.com/settings/api-tokens.
Response format.
jsonPossible values: Report revision to serve. Use latest to request the highest
supported revision for this report. The served revision is echoed
in the X-Swarmia-Report-Revision response header.
The deprecated version query parameter is accepted as an alias.
1Start of the reporting period (inclusive).
2026-01-01End of the reporting period (inclusive).
2026-02-01IANA timezone used to interpret the date-only timeframe.start
and timeframe.end values and for time bucketing. Defaults to
the organization's timezone configured in Swarmia, so results
match the app. Pass UTC explicitly for UTC-based windows.
America/New_YorkControls weekend exclusion for cycleTime and mergeTime. When
omitted, the report follows the organization's Metric calculation
setting. An explicit true or false overrides that setting for
this request. timeToFirstReview always excludes weekends.
falseComma-separated team UUIDs. Only these teams are included.
Use either this or parentTeamId, not both. Omit both to
return all teams.
4d9361ab-3217-4690-957e-ca69abe9ca07,972cedde-3104-454a-a048-f27f43539442Comma-separated parent-team UUIDs. Returns the children of these
teams (not the parents themselves). Use the literal value null
(or an empty value) to select only top-level teams (teams with no
parent). Use either this or teamId, not both. Omit both to
return all teams.
nullNumeric aggregation applied to the metrics. Affects every metric
whose schema entry reports a configurable aggregate (e.g.
cycleTime, changeLeadTimeAgg). Metrics with a fixed aggregate
(counts, rates) are unaffected. Defaults to Avg.
AvgExample: P90Possible values: Aggregate data only from pull requests matching the given filter. Uses the same entity-filter format as the Swarmia UI's similarly named query parameter.
Successful response.
Invalid or unknown parameters.
Missing or invalid API token.
GET /api/v1/reports/metrics/code?revision=1&timeframe.start=2026-01-01&timeframe.end=2026-02-01 HTTP/1.1
Host: app.swarmia.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"schema": {
"_key": {
"title": "Team",
"description": "Teams represent your organization structure and are the owners of other entities like Issues and Pull requests."
},
"cycleTime": {
"title": "Cycle time",
"description": "Aggregated pull request cycle time, in seconds.",
"aggregate": "Avg"
},
"reviewRate": {
"title": "Review rate",
"description": "The rate of pull requests that have been approved.",
"aggregate": "BooleanAvg"
},
"timeToFirstReview": {
"title": "Time to first review",
"description": "Aggregated time spent waiting for the first review, in seconds.",
"aggregate": "Avg"
},
"mergedCount": {
"title": "Merged PRs",
"description": "The number of merged pull requests.",
"aggregate": "Count"
},
"mergeTime": {
"title": "Merge time",
"description": "Aggregated time spent waiting to merge after approval, in seconds.",
"aggregate": "Avg"
},
"batchSize": {
"title": "Batch size",
"description": "Aggregated batch size (lines changed) of pull requests.",
"aggregate": "Avg"
},
"contributorCount": {
"title": "Contributors",
"description": "Number of unique contributors.",
"aggregate": "CountDistinct"
},
"averageInProgress": {
"title": "PRs in progress",
"description": "Number of pull requests in progress on average. Always an average, regardless of the chosen aggregate.",
"aggregate": "Custom"
},
"teamFte": {
"title": "FTE",
"description": "Average number of active developers (full-time equivalent) during the timeframe.",
"aggregate": "Custom"
},
"mergedPrsByFte": {
"title": "Merged PRs / FTE",
"description": "Number of merged pull requests per active developer (full-time equivalent) during the timeframe."
}
},
"rows": [
{
"_key": {
"type": "Team",
"id": "d8345f20-7c0f-4709-b1c7-cd7e0444da46",
"name": "Frontend"
},
"id": "d8345f20-7c0f-4709-b1c7-cd7e0444da46",
"name": "Frontend",
"cycleTime": 3600,
"reviewRate": 100,
"timeToFirstReview": 60,
"mergedCount": 1,
"mergeTime": 3480,
"batchSize": 2,
"contributorCount": 1,
"averageInProgress": 0.0059,
"teamFte": null,
"mergedPrsByFte": null
}
],
"summaryRow": {
"id": null,
"name": null,
"cycleTime": 3600,
"reviewRate": 100,
"timeToFirstReview": 60,
"mergedCount": 1,
"mergeTime": 3480,
"batchSize": 2,
"contributorCount": 1,
"averageInProgress": 0.0059,
"teamFte": null,
"mergedPrsByFte": null
}
}Overview of DORA metrics, mirroring the DORA metrics — Overview report in the app. All metrics are restricted to production deployments within the requested timeframe.
Durations (changeLeadTimeAgg, releaseTimeAgg, timeToRecoveryAgg) are in seconds. changeFailureRateAgg is a rate. The numeric aggregate parameter controls how the duration metrics are aggregated.
The report runs in one of two modes:
Organization mode (no
teamId/parentTeamId): returns a single row keyed by the organization, aggregating all production deployments — including those not owned by any team.Team mode (
teamIdorparentTeamIdgiven): returns one row per matched team, scoped to deployments owned by that team, plus asummaryRow.
Supported revisions: 1, 2 (latest is equivalent to 2). Revision 2 treats teamId/parentTeamId as comma-separated lists and adds parentTeamId support. In revision 1, supplying teamId returns that team's child teams only (the team itself is excluded from rows but still counted in summaryRow).
API token passed as Authorization: Bearer <token>.
The token must have the scope required by the endpoint.
Tokens can be provisioned at https://app.swarmia.com/settings/api-tokens.
Response format.
jsonPossible values: Report revision to serve. Use latest to request the highest
supported revision for this report. The served revision is echoed
in the X-Swarmia-Report-Revision response header.
The deprecated version query parameter is accepted as an alias.
1Start of the reporting period (inclusive).
2026-01-01End of the reporting period (inclusive).
2026-02-01IANA timezone used to interpret the date-only timeframe.start
and timeframe.end values and for time bucketing. Defaults to
the organization's timezone configured in Swarmia, so results
match the app. Pass UTC explicitly for UTC-based windows.
America/New_YorkComma-separated team UUIDs. Only these teams are included.
Use either this or parentTeamId, not both. Omit both to
return all teams.
4d9361ab-3217-4690-957e-ca69abe9ca07,972cedde-3104-454a-a048-f27f43539442Comma-separated parent-team UUIDs. Returns the children of these
teams (not the parents themselves). Use the literal value null
(or an empty value) to select only top-level teams (teams with no
parent). Use either this or teamId, not both. Omit both to
return all teams.
nullNumeric aggregation applied to the metrics. Affects every metric
whose schema entry reports a configurable aggregate (e.g.
cycleTime, changeLeadTimeAgg). Metrics with a fixed aggregate
(counts, rates) are unaffected. Defaults to Avg.
AvgExample: P90Possible values: Successful response.
Invalid or unknown parameters.
Missing or invalid API token.
GET /api/v1/reports/metrics/dora?revision=1&timeframe.start=2026-01-01&timeframe.end=2026-02-01 HTTP/1.1
Host: app.swarmia.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"schema": {
"_key": {
"title": "Team",
"description": "Teams represent your organization structure and are the owners of other entities like Issues and Pull requests."
},
"changeLeadTimeAgg": {
"title": "Change lead time",
"description": "Aggregated change lead time, in seconds.",
"aggregate": "Avg"
},
"releaseTimeAgg": {
"title": "Release time",
"description": "Aggregated release (time to deploy) time, in seconds.",
"aggregate": "Avg"
},
"deploymentCount": {
"title": "Deployment count",
"description": "Number of production deployments in the timeframe.",
"aggregate": "Count"
},
"timeToRecoveryAgg": {
"title": "Time to recovery",
"description": "Aggregated time for failed deployments to be fixed, in seconds.",
"aggregate": "Avg"
},
"changeFailureRateAgg": {
"title": "Change failure rate",
"description": "The rate of failed deployments.",
"aggregate": "Custom"
}
},
"rows": [
{
"_key": {
"type": "Team",
"id": "d8345f20-7c0f-4709-b1c7-cd7e0444da46",
"name": "Frontend"
},
"id": "d8345f20-7c0f-4709-b1c7-cd7e0444da46",
"name": "Frontend",
"changeLeadTimeAgg": 86400,
"releaseTimeAgg": 1800,
"deploymentCount": 12,
"timeToRecoveryAgg": 3600,
"changeFailureRateAgg": 0.08
}
],
"summaryRow": {
"id": null,
"name": null,
"changeLeadTimeAgg": 86400,
"releaseTimeAgg": 1800,
"deploymentCount": 12,
"timeToRecoveryAgg": 3600,
"changeFailureRateAgg": 0.08
}
}Overview of AI assistant usage in the organization.
Supported revisions: 1 (latest is equivalent).
API token passed as Authorization: Bearer <token>.
The token must have the scope required by the endpoint.
Tokens can be provisioned at https://app.swarmia.com/settings/api-tokens.
Response format.
jsonPossible values: Report revision to serve. Use latest to request the highest
supported revision for this report. The served revision is echoed
in the X-Swarmia-Report-Revision response header.
The deprecated version query parameter is accepted as an alias.
1Start of the reporting period (inclusive).
2026-01-01End of the reporting period (inclusive).
2026-02-01IANA timezone used to interpret the date-only timeframe.start
and timeframe.end values and for time bucketing. Defaults to
the organization's timezone configured in Swarmia, so results
match the app. Pass UTC explicitly for UTC-based windows.
America/New_YorkComma-separated team UUIDs. Only these teams are included.
Use either this or parentTeamId, not both. Omit both to
return all teams.
4d9361ab-3217-4690-957e-ca69abe9ca07,972cedde-3104-454a-a048-f27f43539442Comma-separated parent-team UUIDs. Returns children of these
teams. Use the literal value null (or an empty value) to
select only top-level teams (teams with no parent).
Use either this or teamId, not both. Omit both to return
all teams.
nullWhen true (default), only count team members who opened at
least one PR during the time period. When false, count all
team members.
trueComma-separated list of AI assistants to include. Omit to include all.
GithubCopilot,Cursor,ClaudeCodeSuccessful response.
Invalid or unknown parameters.
Missing or invalid API token.
GET /api/v1/reports/ai/adoption/users-and-licenses?revision=1&timeframe.start=2026-01-01&timeframe.end=2026-02-01 HTTP/1.1
Host: app.swarmia.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"schema": {
"_key": {
"title": "Team",
"description": "Teams represent your organization structure and are the owners of other entities like Issues and Pull requests."
},
"enabledAiUsers": {
"title": "AI tool enabled users",
"description": "The ID of the author of the activity",
"aggregate": "ArrayAggDistinct"
},
"activeAiUsers": {
"title": "Active users",
"description": "The ID of the author of the activity",
"aggregate": "ArrayAggDistinct"
},
"enabledAiUserCount": {
"title": "AI tool enabled user count",
"description": "Contributors with an AI tool license at some point during the calendar weeks in the time period.",
"aggregate": "CountDistinct"
},
"activeAiUserCount": {
"title": "Active user count",
"description": "Contributors who used an AI tool at some point during the calendar weeks in the time period.",
"aggregate": "CountDistinct"
},
"contributorCount": {
"title": "Contributors",
"description": "Number of team members who created at least one PR during the time period.",
"aggregate": "CountDistinct"
},
"weeklyActiveAvg": {
"title": "Weekly active, avg.",
"description": "Average number of active users per week. Calculated as total active users divided by number of weeks in the time period."
},
"enabledRate": {
"title": "Enabled rate",
"description": "AI tool enabled / contributors"
}
},
"rows": [
{
"_key": {
"type": "Team",
"id": "d8345f20-7c0f-4709-b1c7-cd7e0444da46",
"name": "Frontend"
},
"enabledAiUsers": [
{
"type": "Author",
"id": "670f1dcf-e026-4551-af08-d27c39865995",
"name": "Alice",
"email": "alice@example.com"
}
],
"activeAiUsers": [
{
"type": "Author",
"id": "670f1dcf-e026-4551-af08-d27c39865995",
"name": "Alice",
"email": "alice@example.com"
}
],
"enabledAiUserCount": 1,
"activeAiUserCount": 1,
"contributorCount": 1,
"weeklyActiveAvg": 1,
"enabledRate": 100
},
{
"_key": {
"type": "Team",
"id": "6d7db279-6112-4271-b197-84066b631db2",
"name": "Backend"
},
"enabledAiUsers": [
{
"type": "Author",
"id": "98078272-8f5c-450e-bea7-6424a70f1d49",
"name": "Bob",
"email": "bob@example.com"
}
],
"activeAiUsers": [],
"enabledAiUserCount": 1,
"activeAiUserCount": 0,
"contributorCount": 1,
"weeklyActiveAvg": 0,
"enabledRate": 100
}
],
"summaryRow": {
"enabledAiUsers": [
{
"id": "670f1dcf-e026-4551-af08-d27c39865995",
"type": "Author",
"name": "Alice",
"email": "alice@example.com"
},
{
"id": "98078272-8f5c-450e-bea7-6424a70f1d49",
"type": "Author",
"name": "Bob",
"email": "bob@example.com"
}
],
"activeAiUsers": [
{
"id": "670f1dcf-e026-4551-af08-d27c39865995",
"type": "Author",
"name": "Alice",
"email": "alice@example.com"
}
],
"enabledAiUserCount": 2,
"activeAiUserCount": 1,
"contributorCount": 2,
"weeklyActiveAvg": 1,
"enabledRate": 100
}
}Last updated
Was this helpful?