Full API and Integration Documentation

Metrics

Public metrics are a great way to build trust and transparency around your organization, and ensure that your page is doing work for you each and every day.

Get a list of available public metric providers

StatusPage.io supports 5 awesome vendors that hold a lot of internal data that companies may want to display on their status page. We also support a "Self" provider for you to send us custom metrics if you wish. Each metric provider is listed along with its required fields for linking.

ENDPOINT
  GET /metrics_providers.json

SAMPLE CALL
  curl https://api.statuspage.io/v1/metrics_providers.json

RESPONSE CODES
  200 - Successful call

SAMPLE RESPONSE
  [
    {
      "required_fields": [
        "email",
        "password",
        "application_key"
      ],
      "type": "Pingdom"
    },
    {
      "required_fields": [
        "api_key"
      ],
      "type": "NewRelic"
    },
    {
      "required_fields": [
        "email",
        "api_token"
      ],
      "type": "Librato"
    },
    {
      "required_fields": [
        "api_key",
        "application_key"
      ],
      "type": "Datadog"
    },
    {
      "required_fields": [],
      "type": "Self"
    }
  ]

Get a list of metric providers linked to your page
ENDPOINT
  GET /pages/[page_id]/metrics_providers.json

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/95p5y625sm2m/metrics_providers.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074"

RESPONSE CODES
  200 - Successful call

SAMPLE RESPONSE
  [
    {
      "created_at": "2013-09-21T22:10:26Z",
      "disabled": false,
      "id": "yy59xsy7xykv",
      "last_revalidated_at": "2013-09-30T16:22:57Z",
      "page_id": "95p5y625sm2m",
      "type": "NewRelic",
      "updated_at": "2013-09-30T16:22:58Z"
    },
    {
      "created_at": "2013-09-30T16:24:07Z",
      "disabled": false,
      "id": "cm7f8dghrtzn",
      "last_revalidated_at": "2013-09-30T16:24:07Z",
      "page_id": "95p5y625sm2m",
      "type": "Librato",
      "updated_at": "2013-09-30T16:24:07Z"
    }
  ]
Get a list of metrics created for a linked metrics provider
ENDPOINT
  GET /pages/[page_id]/metrics_providers/[metrics_provider_id]/metrics.json

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/95p5y625sm2m/metrics_providers/yy59xsy7xykv/metrics.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074"

RESPONSE CODES
  200 - Successful call

SAMPLE RESPONSE
  [
    {
      "application_id": "1887052",
      "application_name": "StatusPage.io",
      "backfill_percentage": 1.0,
      "backfilled": true,
      "created_at": "2013-09-30T16:38:12Z",
      "decimal_places": 3,
      "display": true,
      "id": "x6mjd19qxyx2",
      "last_fetched_at": "2013-09-30T16:41:59Z",
      "metric_identifier": "Real User Apdex",
      "metrics_provider_id": "yy59xsy7xykv",
      "most_recent_data_at": "2013-09-30T16:40:00Z",
      "name": "Real User Apdex",
      "suffix": "",
      "tooltip_description": "",
      "updated_at": "2013-09-30T16:40:08Z",
      "y_axis_max": null,
      "y_axis_min": 0.0
    },
    {
      "application_id": "1887052",
      "application_name": "StatusPage.io",
      "backfill_percentage": 1.0,
      "backfilled": true,
      "created_at": "2013-09-30T16:39:53Z",
      "decimal_places": 0,
      "display": true,
      "id": "l5lx859p1pkh",
      "last_fetched_at": "2013-09-30T16:42:02Z",
      "metric_identifier": "Response Time",
      "metrics_provider_id": "yy59xsy7xykv",
      "most_recent_data_at": "2013-09-30T16:42:01Z",
      "name": "Server Response Time",
      "suffix": "ms",
      "tooltip_description": null,
      "updated_at": "2013-09-30T16:40:18Z",
      "y_axis_max": null,
      "y_axis_min": 0.0
    }
  ]
Create a custom metric
ENDPOINT
  POST /pages/[page_id]/metrics_providers/[metrics_provider_id]/metrics.json

MUTABLE FIELDS
  metric[name] - Display name for the metric
  metric[suffix] - Suffix or units for the metric (ms, req/min, %, etc)
  metric[display] - 't' or 'f', whether or not to immediately show the metric on your page (defaults to 'f')
  metric[tooltip_description] - Description of the metric as displayed on the page in a tooltip
  metric[y_axis_min] - Minimum value for the Y-axis display
  metric[y_axis_max] - Maximum value for the Y-axis display
  metric[decimal_places] - Amount of decimal places to use in the display of values and the average over a time period

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/95p5y625sm2m/metrics_providers/40ns6wgryb7c/metrics.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -X POST \
    -d "metric[name]=Scott's Metric" \
    -d "metric[suffix]=widgets/sec" \
    -d "metric[tooltip_description]=Amount of widgets created every second in the ScottCo factory" \
    -d "metric[y_axis_min]=0" \
    -d "metric[decimal_places]=1"

RESPONSE CODES
  201 - Successfully created
  422 - Validation errors

SAMPLE RESPONSE
  {
    "backfilled": false,
    "created_at": "2013-09-30T18:12:46Z",
    "decimal_places": 0,
    "display": false,
    "id": "bhy703cqvxgy",
    "metric_identifier": null,
    "metrics_provider_id": "40ns6wgryb7c",
    "most_recent_data_at": null,
    "name": "Scott's Metric",
    "suffix": "widgets/sec",
    "tooltip_description": "Amount of widgets created every second in the ScottCo factory",
    "updated_at": "2013-09-30T18:12:46Z",
    "y_axis_max": null,
    "y_axis_min": 0.0
  }
Submit data for a custom metric

Submitting data for a custom metric is as easy as sending a POST request with the timestamp and value of the data point. Take note that there are a couple constraints and considerations when submitting data:

  • At minimum, one data point must be submitted every 5 minutes. If there is a lag in data, the gap will be reflected on the charts for the "Day" view.
  • Each data point is cast to its nearest 30s interval, giving us a maximum of 10 data points per 5 minute period. Submitting multiple data points near each other will result in the last data point being the only one stored.
  • The timestamp value returned in the body of the response will be the casted timestamp used to store your data.
  • Data can, and should, be backfilled up to 28 days in the past.
ENDPOINT
  POST /pages/[page_id]/metrics/[metric_id]/data.json

REQUIRED FIELDS
  data[timestamp] - Unix timestamp for the data point
  data[value] - Value of the data point (int or float)

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/95p5y625sm2m/metrics/bhy703cqvxgy/data.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -X POST \
    -d "data[timestamp]=1380568670" \
    -d "data[value]=4815.162342"

RESPONSE CODES
  201 - Successfully created
  405 - Data cannot be submitted for this type of metric
  422 - Validation errors

SAMPLE RESPONSE
  {
    "data": {
      "timestamp":1380568650,
      "value":4815.162342
    }
  }
Submit data for multiple custom metrics

Submitting data for multiple custom metrics allows you to cut down on significant amounts of HTTP requests, and can vastly simply your integraiton with the API.

  • All conditions above apply for this endpoint.
  • A maximum of 3000 data points per request can be submitted.
ENDPOINT
  POST /pages/[page_id]/metrics/data.json

REQUIRED FIELDS
  data - A hash of metric IDs, each having an array of timestamp/value pairs

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/95p5y625sm2m/metrics/data.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -X POST \
    -d "data[bhy703cqvxgy][][timestamp]=1380568670" \
    -d "data[bhy703cqvxgy][][value]=4815.162342" \
    -d "data[bhy703cqvxgy][][timestamp]=1380568700" \
    -d "data[bhy703cqvxgy][][value]=4813.21" \
    -d "data[hjkl5678aabb][][timestamp]=1380568670" \
    -d "data[hjkl5678aabb][][value]=40" \
    -d "data[hjkl5678aabb][][timestamp]=1380568700" \
    -d "data[hjkl5678aabb][][value]=41"

SAMPLE RUBY SCRIPT
  require 'httparty'

  dhash = {
    "bhy703cqvxgy" => [
      {
        "timestamp": 1380568670,
        "value": 4815.162342
      },
      {
        "timestamp": 1380568700,
        "value": 4813.21
      }
    ],
    "hjkl5678aabb" => [
      {
        "timestamp": 1380568670,
        "value": 40
      },
      {
        "timestamp": 1380568700,
        "value": 41
      }
    ]
  }

  HTTParty.post(
    "https://api.statuspage.io/v1/pages/95p5y625sm2m/metrics/data.json",
    :headers => {"Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074"},
    :body => {:data => dhash}
  )

RESPONSE CODES
  202 - Batch accepted, will be queued for processing
  403 - Metric not found for ID, or submitted too many data points
  405 - Submitted data point for non-custom metric

SAMPLE RESPONSE
  {
    "bhy703cqvxgy": [
      {
        "timestamp": 1380568670,
        "value": 4815.162342
      },
      {
        "timestamp": 1380568700,
        "value": 4813.21
      }
    ],
    "hjkl5678aabb": [
      {
        "timestamp": 1380568670,
        "value": 40
      },
      {
        "timestamp": 1380568700,
        "value": 41
      }
    ]
  }
Delete all data for a custom metric
ENDPOINT
  DELETE /pages/[page_id]/metrics/[metric_id]/data.json

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/95p5y625sm2m/metrics/bhy703cqvxgy/data.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -X DELETE

RESPONSE CODES
  200 - Successfully deleted data

SAMPLE RESPONSE
  {
    "backfilled": false,
    "created_at": "2013-09-30T18:12:46Z",
    "decimal_places": 0,
    "display": false,
    "id": "bhy703cqvxgy",
    "metric_identifier": null,
    "metrics_provider_id": "40ns6wgryb7c",
    "most_recent_data_at": null,
    "name": "Scott's Metric",
    "suffix": "widgets/sec",
    "tooltip_description": "Amount of widgets created every second in the ScottCo factory",
    "updated_at": "2013-09-30T18:12:46Z",
    "y_axis_max": null,
    "y_axis_min": 0.0
  }