Explore documentation
  1. Welcome to Incidents 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Tag on-call in Slack
    4. Mobile apps ↗
    5. Connecting external calendars
    6. Advanced guide
  4. Incident management
    1. Get started
    2. AI SRE investigations
    3. Post mortems
    4. Metadata & Catalog
    5. Screening alerts
    6. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Incidents API
    1. Getting an API token
    2. Pagination
    3. Monitors
    4. Heartbeats
    5. On-call & incidents
    6. Status pages
    7. Metadata
      1. Metadata API
        1. List metadata GET
        2. Update metadata POST
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

List metadata

List metadata for given incident, monitor, or other resources.

GET https://incidents.betterstack.com/api/v3/metadata

Query parameters

team_name
string

Filter metadata belonging to a specified team when using global API token.

owner_id
string

Resource to return metadata for. Metadata for all resources will be returned if omitted.

owner_type
string

Type of resource to return metadata for. Accepted values: Monitor, Heartbeat, Incident, WebhookIntegration, EmailIntegration, IncomingWebhook, AmazonSnsIntegration, or CallRouting.

page
integer

The page number to return, starting with 1.

per_page
integer

Number of results per page. Defaults to 50, maximum 250.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns a list of existing metadata, one record per key and resource.

Response body

{
  "data": [
    {
      "id": "25",
      "type": "metadata",
      "attributes": {
        "key": "Key 1",
        "values": [
          {
            "type": "String",
            "value": "Value 1"
          },
          {
            "type": "String",
            "value": "Value 2"
          }
        ],
        "team_name": "Testing",
        "owner_id": "2",
        "owner_type": "Monitor"
      },
      "relationships": {
        "owner": {
          "data": {
            "id": "2",
            "type": "monitor"
          }
        }
      }
    },
    {
      "id": "23",
      "type": "metadata",
      "attributes": {
        "key": "Key 2",
        "values": [
          {
            "type": "Schedule",
            "item_id": 123,
            "name": "Secondary calendar"
          }
        ],
        "team_name": "Testing",
        "owner_id": "30579",
        "owner_type": "WebhookIntegration"
      },
      "relationships": {
        "owner": {
          "data": {
            "id": "30579",
            "type": "webhook_integration"
          }
        }
      }
    }
  ],
  "pagination": {
    "first": "https://incidents.betterstack.com/api/v3/metadata?page=1",
    "last": "https://incidents.betterstack.com/api/v3/metadata?page=4",
    "prev": null,
    "next": "https://incidents.betterstack.com/api/v3/metadata?page=2"
  }
}

Response attributes

id
string

The ID of the metadata record, which is the ID of the first of its values.

type
string

Always metadata.

attributes.key
string

The metadata key.

attributes.values
array

All values the resource has under this key.

attributes.values[].type
string

The type of the value: String, User, Team, Policy, Schedule, Endpoint, Source, SlackIntegration, LinearIntegration, JiraIntegration, MicrosoftTeamsWebhook, ZapierWebhook, NativeWebhook, or PagerDutyWebhook. Endpoint is a monitor and Schedule an on-call calendar.

attributes.values[].value
string

The text of a String value.

attributes.values[].item_id
integer

The ID of the item a value of any other type references.

attributes.values[].name
string or null

The name of the referenced item.

attributes.values[].email
string

The e-mail of the referenced user, only when type is User.

attributes.team_name
string

The team the metadata belongs to.

attributes.owner_id
string

The ID of the resource the metadata belongs to.

attributes.owner_type
string

The type of the resource: Monitor, Heartbeat, Incident, WebhookIntegration, EmailIntegration, IncomingWebhook, AmazonSnsIntegration, or CallRouting.

relationships.owner
object

The same resource as a relationship, kept for backward compatibility. Use owner_id and owner_type instead.

pagination.first
string

The URL of the first page. Read more about pagination.

pagination.last
string

The URL of the last page.

pagination.prev
string or null

The URL of the previous page, or null on the first page.

pagination.next
string or null

The URL of the next page, or null on the last page.

Example cURL

Example
curl --request GET \
  --url "https://incidents.betterstack.com/api/v3/metadata?owner_id=2&owner_type=Monitor" \
  --header 'authorization: Bearer $TOKEN'


Previous article

Remove status update

Next article

Update metadata