Docs
circleci.com
Start Building for Free

Insights Snapshot Badge

1 month ago1 min read
Cloud
On This Page

Overview

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.

Insights snapshot badge embedded on README

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.

Generating 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:

[![CircleCI](https://dl.circleci.com/insights-snapshot/gh/circleci/circleci-docs/master/build-deploy/badge.svg?window=30d)](https://app.circleci.com/insights/github/circleci/circleci-docs?branches=master&workflows=build-deploy&reporting-window=last-30-days&insights-snapshot=true)

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


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.

Need support?

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.