Book a demoLog in

Export API

Swarmia provides an API for exporting data into e.g. spreadsheets or dashboards.

Overview

Swarmia provides a simple GET API for exporting reporting data. The APIs can be used e.g. on Google Spreadsheets (with =IMPORTDATA("URL")).

Base URL
https://app.swarmia.com/api/v0

Authentication

Authentication works based on a token shared with you (no UI to create or rotate secrets yet).

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

Example request
curl https://app.swarmia.com/api/v0/reports/dora -H "Authorization: Bearer {TOKEN}"

Option 2: Token as query parameter

Pass the token as a value for the token query parameter. 

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

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.

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)

    • 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

https://app.swarmia.com/api/v0/reports/capex?startDate=<firstDayOfMonth>&endDate=<lastDayOfMonth>

Returns a software capitalization report in CSV format.

Note: Both the start and end dates must be within the same year

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=<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

  • <first day of month> The employee’s total FTEs of that month

Effort reporting

https://app.swarmia.com/api/v0/reports/fte?month=<month>

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

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

PreviousExport data as a CSV fileNextOther integrations

Last updated

Was this helpful?