Custom Reports

Any custom reports created at https://app.swarmia.com/explore become automatically available under this API. Go to Explore, save a report, then use its UUID to fetch results via the API. The specific properties available on the response rows depend on the report in question.

Custom report saved in the app

get

Executes a custom report and returns the results. Custom reports are created at app.swarmia.com/explore. The id parameter expected by the API is the UUID shown in the report's URL in the app (query parameter activeReport=<UUID>).

The response shape (columns, aggregates, grouping) is fully determined by the report. The schema object in the response describes each column so consumers can interpret the dynamic result.

Results are paginated. Use limit / offset to page through the rows; the response carries a pagination object (hasMore, nextOffset, and totalRows when includeTotal=true). When more rows are available, the next page's offset is also returned in the Link: …; rel="next" and X-Swarmia-Next-Offset response headers, which you can follow rather than computing offsets yourself.

CSV output (output=csv) ignores limit/offset and streams the full result set up to a cap of 10000 rows, setting the X-Swarmia-Result-Truncated: true header when the result was capped.

Authorizations

AuthorizationstringRequired

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.

Path parameters

idstring · uuidRequired

UUID of a custom report.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Query parameters

outputstring · enumOptional

Response format.

Default: jsonPossible values:

limitinteger · min: 1 · max: 1000Optional

Maximum number of rows to return in one page. Must be a positive integer no larger than 1000. Defaults to 100 when omitted.

Ignored for output=csv, which always streams the full result set (see the text/csv response).

Default: 100Example: 100

offsetinteger · max: 100000Optional

Number of rows to skip before the page starts, for paging through a large result set. Must be a non-negative integer no larger than 100000. Defaults to 0.

Prefer following the nextOffset value (or the Link/ X-Swarmia-Next-Offset response header) rather than computing offsets yourself.

Ignored for output=csv.

Default: 0Example: 100

includeTotalbooleanOptional

When true, the response pagination object includes a totalRows count of all rows matching the query (ignoring limit/offset). Computing the total is more expensive, so it is omitted by default.

Default: falseExample: true

timeframe.startstring · dateOptional

Start of the reporting period (inclusive). When provided together with timeframe.end, overrides all timeframe filters embedded in the report. When omitted, the report's original timeframes are used as-is.

Example: 2026-01-01

timeframe.endstring · dateOptional

End of the reporting period (inclusive). Must be provided together with timeframe.start.

Example: 2026-02-01

timezonestringOptional

IANA 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.

Example: America/New_York

Responses

200

Successful response.

400

Invalid or unknown parameters.

application/json

401

Missing or invalid API token.

404

Report not found.

get/reports/custom/{id}

GET /api/v1/reports/custom/{id} 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."
    },
    "id": {
      "title": "Team",
      "description": "Teams represent your organization structure and are the owners of other entities like Issues and Pull requests."
    },
    "membersCount": {
      "title": "Member count",
      "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.)",
      "aggregate": "Count"
    },
    "prCycleTimeAvg": {
      "title": "Cycle time, avg",
      "description": "The duration in seconds the pull request has been worked on.",
      "aggregate": "Avg"
    }
  },
  "rows": [
    {
      "_key": {
        "type": "Team",
        "id": "d8345f20-7c0f-4709-b1c7-cd7e0444da46",
        "name": "Frontend"
      },
      "id": "d8345f20-7c0f-4709-b1c7-cd7e0444da46",
      "membersCount": 18,
      "prCycleTimeAvg": 127222.55
    },
    {
      "_key": {
        "type": "Team",
        "id": "6d7db279-6112-4271-b197-84066b631db2",
        "name": "Backend"
      },
      "id": "6d7db279-6112-4271-b197-84066b631db2",
      "membersCount": 37,
      "prCycleTimeAvg": 107886.23
    },
    {
      "_key": {
        "type": "Team",
        "id": "a3c8e1f0-5b2d-4a91-9c67-3f8d2e1a4b5c",
        "name": "Platform"
      },
      "id": "a3c8e1f0-5b2d-4a91-9c67-3f8d2e1a4b5c",
      "membersCount": 2,
      "prCycleTimeAvg": 41976.51
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextOffset": 100,
    "totalRows": 142
  }
}