Insights Snapshot Badge

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:

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:

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.