---
title: "Custom report saved in the app"
method: GET
path: "/reports/custom/{id}"
tags: ["Custom reports"]
---

# Custom report saved in the app

`GET /reports/custom/{id}`

Executes a custom report and returns the results. Custom
reports are created at
[app.swarmia.com/explore](https://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.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `output` 'json' | 'csv'
- `limit` integer
- `offset` integer
- `includeTotal` boolean
- `timeframe.start` string, date
- `timeframe.end` string, date
- `timezone` string

## Response `200`

Successful response.

- EntityReportCustomResult
  - `schema` object, required — Describes each property in `rows`. Keys are property names, values carry things like a human-readable `title`, `description`, etc. The exact properties depend on the report's configuration.
  - `rows` object[], required — Data rows from the report. Each row has a `_key` identifying the entity or group the row represents, plus dynamic properties matching the keys in `schema`.
    - `_key` union, required — Row identifier. Shape depends on the report's grouping — an entity reference for entity-grouped reports, or any property value for other groupings.
      - union — A reference to an entity. Discriminated by `type`.
        - EntityReferenceTeam — Teams represent your organization structure and are the owners of other entities like Issues and Pull requests.
          - `type` 'Team', required
          - `id` string, uuid, required
          - `name` string, required
        - EntityReferenceAuthor — 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.)
          - `id` string, uuid, required
          - `type` 'Author', required
          - `name` string, nullable, required
          - `email` string, nullable, required
        - EntityReferenceOrganization — The organization that the API token belongs to.
          - `type` 'Organization', required
          - `id` string, uuid, required
          - `name` string, nullable
      - unknown
  - `summaryRow` object — Aggregate across all rows. Same dynamic properties as each row but without `_key`. Only present when enabled in the report.
  - `pagination` Pagination — Paging metadata for the current page. Only present on JSON responses (CSV streams the full result set instead).
    - `hasMore` boolean, required — Whether more rows are available beyond this page.
    - `nextOffset` integer, nullable, required — The `offset` to request the next page, or `null` when there are no more rows (`hasMore` is `false`).
    - `totalRows` integer — Total number of rows matching the query, ignoring `limit`/`offset`. Only present when `includeTotal=true` was requested.

## Other responses

- `400` — Invalid or unknown parameters.
- `401` — Missing or invalid API token.
- `404` — Report not found.

---

[API](https://skmtc.net/swarmia/apis/swarmia-rest-api.md) · [All operations](https://skmtc.net/swarmia/apis/swarmia-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/swarmia/swarmia-rest-api/revisions/68d401c79425/schema)