Insights Snapshot Badge
On This Page
|The Insights snapshot badge is not currently supported for GitLab or GitHub App projects. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the GitHub App integration 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.
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:
The following is an example of a Insights snapshot badge generated for our CircleCI documentation repository, in Markdown:
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.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.