# Export API ## Overview Swarmia provides a simple `GET` API for exporting reporting data. The APIs can be used e.g. on Google Spreadsheets (with `=IMPORTDATA("URL")`). * Team-level APIs * [Pull Request metrics](#pull-request-metrics) `/pullRequests` * Organization-level APIs * [DORA metrics](#dora-metrics) `/dora` * [Investment Balance](#investment-balance) `/investment` * [Software Capitalization reporting](#software-capitalization-report) `/capex` * [Software Capitalization employees](#software-capitalization-employees-report) `/capex/employees` * [Effort reporting](#effort-reporting) `/fte` {% code title="Base URL" %} ``` https://app.swarmia.com/api/v0 ``` {% endcode %} ## Authentication Authentication works based on a token shared with you. You can view your tokens and create new ones in [Settings/API tokens](https://app.swarmia.com/settings/api-tokens). Two options are currently available: 1. passing an authorization header, or 2. passing the token as a query parameter. ### Option 1: Authorization header Include an HTTP header like `Authorization: Bearer {TOKEN}` header in the request {% code title="Example request" %} ```bash curl https://app.swarmia.com/api/v0/reports/dora -H "Authorization: Bearer {TOKEN}" ``` {% endcode %} ### Option 2: Token as query parameter Pass the token as a value for the `token` query parameter. ```http GET https://app.swarmia.com/api/v0/reports/dora?token={TOKEN} ``` * **Security note**: even though Swarmia redacts secret tokens from query logs, please bear in mind that some other proxies might log query parameters before reaching Swarmia. ## Timeframes Timeframes can either be defined as one of our presets or as a separate start and end date. **Optional.** By default, we return data for the last 7 days (today included), in the UTC timezone. **How to use** * `timeframe` * `last_7_days` * `last_14_days` * `last_30_days` * `last_60_days` * `last_90_days` * `last_180_days` * `last_365_days` * `startDate` and `endDate` * Dates are defined as `YYYY-MM-DD` * Both ends are inclusive (we include all data on start/end dates to the aggregated result) * `endDate` value needs to be greater than or equal to `startDate` {% hint style="warning" %} **Note:** **Effort** and **Software Capitalization APIs** always require passing timeframes in the request. Use `month` to specify the period you want to export. For exporting **Employees for Software Capitalization**, you need to provide a `year` instead of a date. {% endhint %} ## Timezones By default, we return all data in UTC dates (events are attributed to days based on their UTC timestamps). However, Swarmia’s frontend works based on the user’s browser timezone. To simplify the usability, and especially to help validate data quality with the Swarmia frontend, you can control the timezone used for aggregating event data to the reported date interval. **How to use** * `timezone` * Accepts tz database identifiers ([**listed here**](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) * E.g. `timezone=America/New_York` ## Report data format We return data in a CSV format (delimiter: `,`) which for the moment cannot be configured. This means it’ll work natively on Google Spreadsheets. The returned payload includes a header row. No summary row is included in the export (e.g. when you ask for team data, you will only receive the teams as rows). The columns are documented by endpoint. ## Team-level APIs ### Pull request metrics ``` https://app.swarmia.com/api/v0/reports/pullRequests ``` Returns Pull request metrics for the organization in the timeframe specified. **Data returned** * `Start Date` *(e.g.* `2023-12-31`*)* * `End Date` * `Parent Team(s)` * `Team` *(team’s name on Swarmia)* * `Cycle Time (s)` *(value in seconds)* * `Review Rate (%)` *(percentage value, float)* * `Time to first review (s)` *(value in seconds)* * `PRs merged / week` *(weekly average, float)* * `Merge Time (s)` *(value in seconds)* * `PRs in progress` *(average count)* * `Contributors` *(amount of unique contributors, integer)* **Current limitations** * Only returns specific pull request metrics ## Organization-level APIs ### DORA metrics ``` https://app.swarmia.com/api/v0/reports/dora ``` Returns selected DORA metrics for the organization in the timeframe specified. Beside the general timeframe and timezone settings, accepts these optional query parameters: * `app` * Deployment application name(s), separated by commas if more than one * `environment` * Deployment environment(s), separated by commas if more than one **Data returned** * `Start Date` *(e.g. `2023-12-31`)* * `End Date` * `Deployment Frequency (per day)` * `Change Lead Time Minutes` * `Average Time to Deploy Minutes` * `Change Failure Rate (%)` *(percentage value, float)* * `Mean Time to Recovery Minutes` * `Deployment Count` *(the raw number of all deployments used in aggregations)* **Current limitations** * Deployment Frequency gets returned only per day now, whereas Swarmia UI returns per week numbers for timeframes over 14 days ### Investment Balance 
https://app.swarmia.com/api/v0/reports/investment?startDate=<firstDayOfMonth>&endDate=<lastDayOfMonth>
Returns investment balance statistics using the Effort model, i.e. monthly FTE, for the organization in the specified timeframe that must be provided. Because the underlying data is based on monthly FTE, this API endpoint only accepts a `startDate` that is the first day of a month, and `endDate` that is the last day of a month. The FTE data is generated by default on the 10th day of the next month, so the data for the most recent full month won’t be available before this. **Data returned** * `Start Date` *(e.g. `2023-12-01`)* * `End Date` (*e.g. `2023-12-31`*) * `Investment Category` *(name)* * `FTE months` *(float)* * `Relative Percentage` *(float, 0...100)* * `Commits` *(count)* * `Pull Request Comments` *(count)* * `Pull Request Creations` *(count)* * `Pull Request Merges` *(count)* * `Pull Request Reviews` *(count)* ### Software Capitalization report {% code overflow="wrap" %} ``` https://app.swarmia.com/api/v0/reports/capex?startDate=&endDate= ``` {% endcode %} Returns a software capitalization report in CSV format. {% hint style="warning" %} **Note:** Both the start and end dates must be within the same year {% endhint %} **Query parameters:** * `startDate` **required**. First date of the start month * `endDate` **required**. Last date of the end month **Data returned** * `Month` * `Employee ID` the author’s ID in Swarmia * `Name` * `Email` * `Capitalizable work` the issue title * `Developer months` FTE months contributed by the employee to that issue * `Additional context` value of an issue field that was configured to be included in the report. Only available for Jira issue source. ### Software Capitalization employees ``` https://app.swarmia.com/api/v0/reports/capex/employees?year= ``` Returns the list of employees with a breakdown of their total FTE effort for each month of the year. **Query parameters:** * `year` **required** **Data returned** * `Employee ID` the author’s id in Swarmia * `Name` * `Email` * `` The employee’s total FTEs of that month ### Effort reporting {% code overflow="wrap" %} ``` https://app.swarmia.com/api/v0/reports/fte?month= ``` {% endcode %} Returns the list of authors and their fte for each issue in the given month. **Query parameters:** * `month` **required** * `customField` **optional** → the `jiraFieldId` to be included as the **Custom field** column in the report * `groupBy` **optional** (default: `highestLevelIssue` ) → How the FTE rows in the CSV should be grouped * `highestLevelIssue` → subtasks fte will be grouped into the highest level issue (e.g.: Epic or Story). This is used by default if `groupBy` is not defined. * `lowestLevelIssue` → No extra grouping logic. All effort are exported with their directly linked issue. * `customField` → group by value of the defined `customField` . Also requires `customField` to be specified. When this `groupBy` logic is in use, the returned CSV does not contain `Issue key` and `Swarmia issue type` column, as many issues could be merged into the same `customField` row. **Data returned** * `Month` first day of the month * `Author ID` the author’s id in Swarmia * `Email` the author’s email. The domain is used to detect the primary email. * `FTE` Author’s FTE contribution * `Custom field` Value of the `customField` if defined in the query. If not defined for the issue, then the custom field is inherited from the nearest parent. * When `groupBy` is not defined, or `groupBy` is `highestLevelIssue` or `lowestLevelIssue` : * `Swarmia issue type` * `Issue key` * When `groupBy=customField` * **No** `Swarmia issue type` **nor** `Issue key` fields, as multiple issues may be merged into 1 row with the same `customField` value. --- # 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/data-export/export-api.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.