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. Post mortems
    3. Metadata & Catalog
    4. Screening alerts
    5. 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
    8. Integrations
      1. New Relic
      2. Datadog
      3. AWS CloudWatch
      4. Amazon SNS
      5. Microsoft Azure
      6. Google Monitoring
      7. Grafana
      8. Elastic
      9. Prometheus
      10. E-mail
      11. Incoming webhooks
      12. Atlassian Jira
      13. Slack
      14. Outgoing webhooks
      15. Outgoing e‑mails
      16. Splunk On-Call
      17. PagerDuty
      18. Catalog
        1. Catalog relations
        2. Catalog attributes
        3. Catalog records
          1. List catalog records GET
          2. Get catalog record GET
          3. Create catalog record POST
          4. Update catalog record PATCH
          5. Remove catalog record DELETE
          6. Batch create catalog records POST
          7. Batch update catalog records PUT
          8. Batch upsert catalog records
          9. Batch remove catalog records DELETE
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

List catalog records

Returns a list of all your Catalog records for a Catalog relation.

GET https://incidents.betterstack.com/api/v2/catalog/relations/{relation_id}/records

URL parameters

relation_id
required string

The ID of the Catalog relation you want to get records for.

Query parameters

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 Catalog records.

Response body

{
  "data": [
    {
      "id": "67",
      "type": "catalog_record",
      "attributes": {
        "attributes": [
          {
            "attribute": {
              "id": 56,
              "name": "Team"
            },
            "values": [
              {
                "type": "String",
                "value": "My Team"
              }
            ]
          },
          {
            "attribute": {
              "id": 57,
              "name": "Team Lead"
            },
            "values": [
              {
                "type": "Team",
                "item_id": 123,
                "name": "SRE"
              }
            ]
          }
        ]
      }
    },
    {
      "id": "68",
      "type": "catalog_record",
      "attributes": {
        "attributes": [
          {
            "attribute": {
              "id": 56,
              "name": "Team"
            },
            "values": [
              {
                "type": "String",
                "value": "Another Team"
              }
            ]
          },
          {
            "attribute": {
              "id": 57,
              "name": "Team Lead"
            },
            "values": [
              {
                "type": "Team",
                "item_id": 124,
                "name": "Platform"
              }
            ]
          }
        ]
      }
    }
  ],
  "pagination": {
    "first": "https://incidents.betterstack.com/api/v2/catalog/relations/67/records?page=1",
    "last": "https://incidents.betterstack.com/api/v2/catalog/relations/67/records?page=1",
    "prev": null,
    "next": null
  }
}

Response attributes

id
string

The ID of the Catalog record.

type
string

Always catalog_record.

attributes.attributes
array

The record's values, one entry per Catalog attribute that has values.

attributes.attributes[].attribute
object

The Catalog attribute the values belong to.

attributes.attributes[].attribute.id
integer

The ID of the Catalog attribute.

attributes.attributes[].attribute.name
string

The name of the Catalog attribute.

attributes.attributes[].values
array

The values of this attribute in the record.

attributes.attributes[].values[].type
string

The type of the value: String, User, Team, Policy, Schedule, Endpoint, Source, SlackIntegration, LinearIntegration, JiraIntegration, MicrosoftTeamsWebhook, ZapierWebhook, NativeWebhook or PagerDutyWebhook.

attributes.attributes[].values[].value
string

The value, returned only when type is String.

attributes.attributes[].values[].item_id
integer

The ID of the referenced item, returned when type is not String.

attributes.attributes[].values[].name
string or null

The name of the referenced item, returned when type is not String, or null when the item has no name.

attributes.attributes[].values[].email
string

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

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/v2/catalog/relations/67/records \
  --header "Authorization: Bearer $TOKEN"


Previous article

Remove catalog attribute

Next article

Get a single Catalog record