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.

Authorizations

bearerToken

AuthorizationstringRequired

API token passed as Authorization: Bearer <token>. The token must have the entityQuery scope enabled. 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:

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

Default: UTCExample: America/New_York

Responses

200

Successful response.

application/jsontext/csv

400

Invalid or unknown parameters.

application/json

401

Missing or invalid API token.

404

Report not found.

get

/reports/custom/{id}

HTTPcURLJavaScriptPython

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
    }
  ]
}