# Custom reports Any custom reports created at 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 > 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=\\`).\ > \ > 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.
```json {"openapi":"3.1.0","info":{"title":"Swarmia REST API","version":"1.0"},"tags":[{"name":"Custom reports","description":"Any custom reports created at https://app.swarmia.com/explore become\nautomatically available under this API. Go to Explore, save a report,\nthen use its UUID to fetch results via the API. The specific properties\navailable on the response rows depend on the report in question.\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 `.\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_Custom_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.\nThe exact properties depend on the report's configuration.\n","additionalProperties":{"$ref":"#/components/schemas/SchemaEntry"}},"rows":{"type":"array","description":"Data rows from the report. Each row has a `_key` identifying the entity\nor group the row represents, plus dynamic properties matching the keys in `schema`.\n","items":{"type":"object","required":["_key"],"properties":{"_key":{"description":"Row identifier. Shape depends on the report's grouping —\nan entity reference for entity-grouped reports, or any\nproperty value for other groupings.\n","anyOf":[{"$ref":"#/components/schemas/EntityReference"},{}]}},"additionalProperties":true}},"summaryRow":{"type":"object","description":"Aggregate across all rows. Same dynamic properties as each\nrow but without `_key`. Only present when enabled in the report.\n","additionalProperties":true}}},"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":{"description":"A reference to an entity. Discriminated by `type`.\n","oneOf":[{"$ref":"#/components/schemas/EntityReference_Team"},{"$ref":"#/components/schemas/EntityReference_Author"}]},"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"}}},"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"]}}},"EntityReport_Error":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}},"paths":{"/reports/custom/{id}":{"get":{"tags":["Custom reports"],"operationId":"getReportsCustomById","summary":"Custom report saved in the app","description":"Executes a custom report and returns the results. Custom\nreports are created at\n[app.swarmia.com/explore](https://app.swarmia.com/explore).\nThe `id` parameter expected by the API is the UUID shown in the\nreport's URL in the app (query parameter `activeReport=`).\n\nThe response shape (columns, aggregates, grouping) is fully\ndetermined by the report. The `schema` object in the response\ndescribes each column so consumers can interpret the dynamic\nresult.\n","parameters":[{"name":"id","in":"path","required":true,"description":"UUID of a custom report.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/output"},{"name":"timeframe.start","in":"query","description":"Start of the reporting period (inclusive). When provided\ntogether with `timeframe.end`, overrides **all** timeframe\nfilters embedded in the report. When omitted, the\nreport's original timeframes are used as-is.\n","schema":{"type":"string","format":"date"}},{"name":"timeframe.end","in":"query","description":"End of the reporting period (inclusive). Must be provided\ntogether with `timeframe.start`.\n","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"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityReport_Custom_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."},"404":{"description":"Report not found."}}}}}} ``` --- # 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/custom-reports.md?ask= ``` 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.