Retrieve metric data using the API

Use the Scorecard API endpoints to list available metrics, retrieve values for specific catalog entities, and analyze performance trends for entities or aggregated groups.

Required permissions

Before querying Scorecard endpoints or integrating automated workflows with Scorecard, ensure your account or service token is granted the necessary read permissions.

To use these endpoints, make sure your account has the following permissions:

  • scorecard.metric.read
  • catalog.entity.read (for the specific entities you intend to query)

API endpoints

Use the Scorecard REST API endpoints to programmatically fetch metric definitions, retrieve real-time evaluation values for catalog entities, and aggregate health metrics.

The following table summarizes the available endpoints and their primary functions.

Endpoint Description Query parameters

GET /metrics

Retrieves a list of all available metrics.

metricIds, datasource

GET /metrics/catalog/:kind/:namespace/:name

Retrieves the latest metric values for a specific catalog entity.

metricIds

GET /metrics/:metricId/catalog/aggregations

Retrieves status counts (success, warning, error) for entities you own.

None

API parameter details

Use query and path parameters to narrow down Scorecard metric results and target specific entities within your Software Catalog.

Filtering metrics (GET /metrics)
Use these parameters to refine the list of metrics.
Note

You must not use both parameters in the same request.

Parameter Type Required Description

metricIds

String

No

A comma-separated list of IDs (for example, github.open_prs).

datasource

String

No

Filter by the source ID (for example, github or jira).

Identifying entities (GET /metrics/catalog/…​)
Use path parameters to specify an entity in the Software Catalog.
Parameter Type Required Description

kind

String

Yes

The entity type (for example, component).

namespace

String

Yes

The entity namespace (for example, default).

name

String

Yes

The specific name of the entity.

Troubleshoot API errors

Use the error status code to diagnose parameter conflicts, authorization gaps, or missing catalog references, and apply the required remediation steps.

If a request fails, the API returns a status code and a message. Use the following table to resolve common issues.

Status code Error message Resolution

400 Bad Request

Validation error

Make sure you are not using metricIds and datasource in the same request.

403 Forbidden

Permission denied

Verify that you have both scorecard.metric.read and catalog.entity.read permissions.

404 Not Found

User entity reference not found

Verify that your user account has a defined entity reference in the Software Catalog.