Insights snapshot badge
| This feature is supported for orgs that use OAuth authentication. Check your Organization slug at . OAuth authenticated orgs are structured as follows:
This feature is not supported if your organization slug is in the following format:
For an overview of feature support, see the VCS integration overview page. |
The Insights snapshot badge, similar to a status badge that is commonly embedded in project READMEs, provides a quick view of your project’s health and usage metrics.
Introduction
The most common use case for the Insights snapshot badge is to display Insights metrics for the deployment workflow on the project’s main branch in the README. With that said, the badge can be configured to display Insights metrics for any workflow on any branch within a project. This enables you to create additional badges for your scheduled workflows, workflows with different build targets, or workflows specifically used for testing, to name a few examples.
While commonly placed in a project README, Insights snapshot badges can be embedded in any web document. The badge currently displays the following three metrics from the Insights dashboard:
-
Throughput - The average number of runs of a workflow, over the selected time window.
-
Duration - The 95th percentile duration of the selected workflow, over the specified time window. 95th percentile gives you an idea of the longest duration or time you’re waiting for a build to finish, excluding the last 5 percent, to account for potential transitory spikes.
-
Success Rate - The percentage of successful builds for the selected workflow, over the specified time window.
Generate an Insights snapshot badge
To generate an insights snapshot badge code snippet for a public repository, go to the CircleCI web app, and select a specific project. Then, open Project Settings and navigate to the Insights Snapshot Badge page.
On the Insights Snapshot Badge page, you can select the branch, workflow, and time window for which you want to display project metrics for, as well as the desired format for the code snippet.
You can generate code in the following formats:
-
Image URL
-
Markdown
-
Textile
-
RDoc
-
AsciiDoc
-
reStructuredText
-
Pod
The following is an example of a Insights snapshot badge generated for our CircleCI documentation repository, in Markdown:
[](https://app.circleci.com/insights/github/circleci/circleci-docs?branches=master&workflows=build-deploy&reporting-window=last-30-days&insights-snapshot=true)Create badges for private repositories
To create an Insights snapshot badge for a private project, you will need to create an API token with a scope of “Status” and include that token in the image source URL. If you already have a status badge generated for the same project, you may reuse the same API token for the Insights snapshot badge.
You can add an API token directly from the Insights Snapshot Badge page by clicking on the Add API Token button. This creates an API token with a scope of Status and the label insights-snapshot. (You will also see the new token in your project’s API Permissions settings page.) Your code snippet is displayed after the API token is created.
If you would like to reuse an API token with the scope of Status, which you have already created for your project status badge, you can use one of the following templates as an alternative to the badge generator in the CircleCI web app described above.
In the templates below, replace < > items with your own details. Some options are shown in the table below.
| Item | Options |
|---|---|
|
|
|
|
|
|
|
|