> For the complete documentation index, see [llms.txt](https://docs.statuspal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.statuspal.io/platform/metrics.md).

# Metrics

Publish custom performance metrics to your status page and display them as charts for your customers.

Statuspal lets you publish custom metrics to your status page and display them as line charts. Metrics can represent anything in your system — response times, error rates, throughput, or any other time-series value.

![Example custom metric chart](https://4061983002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgIMm5p2V7PNx3dS7vwKE%2Fuploads%2Fgit-blob-771818bf5bef1e32dfb239aacac4280bee347bab%2Fmetrics-custom-chart-example.png?alt=media)

## Create a custom metric

1. In your status page's dashboard, click **Metrics**, then **New Metric**.
2. Select **Custom Metric** from the **Source** dropdown.\
   \
   ![New custom metric form](https://4061983002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgIMm5p2V7PNx3dS7vwKE%2Fuploads%2Fgit-blob-3fa1a699538c39e3dc54a1e2c0cc3132c2bb1f6c%2Fmetrics-custom-new-metric-form.png?alt=media)
3. Fill in the fields:
   * **Title** — Displayed at the top of the chart.
   * **Unit** — Displayed next to values and the average (e.g. `ms`, `%`, `req/s`).
4. Check **Enabled** and **Visible**, then click **Submit**.

Once created, Statuspal shows you the API endpoint and format for pushing data to this metric.

![API data push instructions](https://4061983002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgIMm5p2V7PNx3dS7vwKE%2Fuploads%2Fgit-blob-9d6343628ad4cb719b285b6a0bd68f7df99e1c02%2Fmetrics-custom-api-instructions.png?alt=media)

## Push data via API

Each data entry requires two fields:

* `timestamp` — UNIX timestamp (seconds)
* `value` — Decimal number

Example using cURL (replace `YOUR_API_KEY`, `STATUS_PAGE_SUBDOMAIN`, and `METRIC_ID` with your values):

```bash
curl -X POST "https://statuspal.io/api/v2/status_pages/STATUS_PAGE_SUBDOMAIN/metrics/METRIC_ID/data_points" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"timestamp": 1700000000, "value": 42.5}'
```

{% hint style="info" %}
Data points appear on the chart as you push them. Use the cURL example shown on the metric's page in the dashboard to run a quick test.
{% endhint %}