# Get SLA by ID

> GET /v1/slas/{id} · Core resources API

Source: https://developer.kustomer.com/api/core-resources/get-sla-by-id

```http
GET https://{orgname}.api.kustomerapp.com/v1/slas/{id}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.sla.read`; or legacy `org.user.sla.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Retrieves an [SLA](https://help.kustomer.com/service-level-agreements-SyZ4xWcgf) based on the unique SLA ID.

Use the optional `versions` query param to retrieve information about SLA versions.

Included SLA version `metrics` may configure **nextReply** (Next Reply time targets per priority) and optional **basedOnHumanInteraction** on **firstResponse** and **nextReply**. When `basedOnHumanInteraction` is `true`, only human-authored SENT outbound messages satisfy the metric. When omitted or `false`, any customer-visible SENT outbound satisfies it (legacy behavior).

## About SLAs

An SLA (service level agreement) is a response-time policy, such as "reply to urgent emails within one hour". Kustomer matches each conversation to one SLA and tracks deadlines for it, so agents can see what's about to breach and managers can report on what did.

Admins define SLAs in the Kustomer admin settings. Each SLA has criteria that decide which conversations it covers, such as a channel or queue, and target times for one or more metrics. SLAs are kept in an order. As conversations change, Kustomer applies the first SLA in that order whose criteria match, then stamps the result on the conversation's `sla` attribute: the SLA name and version, `matchedAt`, a deadline (`breachAt`) and `satisfiedAt` for each metric, and whether and when it `breached`. That conversation attribute is where you read live SLA state. The SLA object itself is the policy.

#### Versions

SLAs are versioned. Every edit creates a new version, `currentVersion` points at the latest, and a conversation records which version it was matched against, so older conversations keep the targets they were measured on. `GET /v1/slas/{id}` returns the SLA's ID and version list; add `versions=active` to include the current version's full definition in `included`, or `versions=all` to include every version.

#### Metrics and targets

A version's `metrics` can enable any of these:

| Metric | Measures |
| --- | --- |
| `firstResponse` | Time from the start of the conversation to the first outbound reply. |
| `nextReply` | Time to answer each new customer message after the first. |
| `longestUnrespondedMessage` | Time from the customer's latest message to an agent reply. |
| `totalConversationOpenTime` | Total time open until done, not counting time snoozed. |
| `totalCustomerWaitTime` | Total time the customer waited for replies, including time snoozed. |

Each metric's `times` holds a target in milliseconds for each conversation priority, keyed `1` to `5`; conversations without a priority use `3`. When `basedOnHumanInteraction` is `true` on `firstResponse` or `nextReply`, only messages written by a person satisfy the metric, so automated replies don't stop the clock.

#### Business hours

`hours` is `calendar` or `business`. Calendar SLAs count every minute. Business SLAs count only while a [business schedule](https://developer.kustomer.com/api/core-resources#business-schedules) is open, skipping nights, weekends and enabled holidays, so a one-hour target set at 4:30 pm on a Friday may not breach until the next business day. A business-hours SLA uses the schedule set on the SLA, or the org's default schedule if none is set.

#### Which endpoint to use

| To | Call |
| --- | --- |
| Look up the policy behind a conversation's `sla`, including its targets | [`GET /v1/slas/{id}`](https://developer.kustomer.com/api/core-resources/get-sla-by-id), with `versions=active` or `versions=all` |

The documented API only reads SLAs; admins create and edit them in the admin settings. To find conversations by SLA state, [search](https://developer.kustomer.com/docs/concepts/search) on attributes such as `conversation_sla_breached`, `conversation_sla_breach_at` and `conversation_sla_status` (`pending`, `paused` or `done`) rather than reading conversations one by one.

Related: [Business schedules](https://developer.kustomer.com/api/core-resources#business-schedules), [Conversations and messages](https://developer.kustomer.com/docs/concepts/conversations-and-messages), [Conversations](https://developer.kustomer.com/api/core-resources#conversations)

### Recipes

#### 1. Show an SLA's targets in minutes

Read the response-time targets of an SLA's current version, for example to show them next to live conversation timers in your own tool.

**Step 1.** [`GET /v1/slas/{id}`](https://developer.kustomer.com/api/core-resources/get-sla-by-id.md). Ask for the SLA with `versions=active`. The version's definition is in the top-level `included`, not in `data`, and kusty prints only `data`, so use cURL. Each enabled metric's `times` maps conversation priority (`1` to `5`) to a target in milliseconds; conversations without a priority use `3`. `hours` says whether the clock runs on `calendar` or `business` time.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/slas/$SLA_ID?versions=active" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  | jq '[.included] | flatten | .[] | .attributes
      | {name, version, hours,
         targets: (.metrics | with_entries(select(.value.enabled) | .value = (.value.times | map_values(. / 60000))))}'
```

> A business-hours SLA only counts time while its [business schedule](https://developer.kustomer.com/api/core-resources#business-schedules) is open, so a 60-minute target can span a night or a weekend.

#### 2. Report breached conversations with the targets they missed

Find the conversations that breached an SLA in a period, then look up the exact version they were measured against, since targets may have changed since.

**Step 1.** [`POST /v1/customers/search`](https://developer.kustomer.com/api/core-resources/create-customer-search.md). Search conversations with `conversation_sla_id`, `conversation_sla_breached` and a date range. Each result's `attributes.sla` holds the `version` it was matched against and, in `breach.metric`, the metric that breached.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/customers/search?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"queryContext\": \"conversation\", \"timeZone\": \"America/New_York\", \"and\": [
    {\"conversation_sla_id\": {\"equals\": \"$SLA_ID\"}},
    {\"conversation_sla_breached\": {\"equals\": true}},
    {\"conversation_created_at\": {\"gte\": \"2026-10-01\"}}]}"
```

```bash title="kusty"
kusty api POST /v1/customers/search --all --data "{\"queryContext\": \"conversation\", \"timeZone\": \"America/New_York\", \"and\": [
    {\"conversation_sla_id\": {\"equals\": \"$SLA_ID\"}},
    {\"conversation_sla_breached\": {\"equals\": true}},
    {\"conversation_created_at\": {\"gte\": \"2026-10-01\"}}]}" \
  | jq -r '[.data.id, .data.attributes.sla.version, .data.attributes.sla.breach.metric] | @tsv' > breaches.tsv
```

**Step 2.** [`GET /v1/slas/{id}`](https://developer.kustomer.com/api/core-resources/get-sla-by-id.md). Fetch every version with `versions=all` and match each conversation's `sla.version` to a version's `version` number to get the target it missed. Use cURL, because the versions are in `included`.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/slas/$SLA_ID?versions=all" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  | jq '[.included] | flatten | map({(.attributes.version | tostring): .attributes.metrics}) | add' > versions.json
```

> Search returns at most 10,000 results per query, so for long periods run one search per week or month. See [Search](https://developer.kustomer.com/docs/concepts/search) for the other `conversation_sla_` attributes, such as `conversation_sla_status`.

### Example object

A real record from [`GET /v1/slas/{id}`](https://developer.kustomer.com/api/core-resources/get-sla-by-id.md):

```json
{
  "type": "sla",
  "id": "5fadc1ba6647f1953ff94916",
  "attributes": {
    "currentVersion": 1,
    "createdAt": "2020-11-12T23:14:02.462Z"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/5d811e40de762100130174a8"
      },
      "data": {
        "type": "org",
        "id": "5d811e40de762100130174a8"
      }
    },
    "createdBy": {
      "links": {
        "self": "/v1/users/5d811e4f6be8d8001391132c"
      },
      "data": {
        "type": "user",
        "id": "5d811e4f6be8d8001391132c"
      }
    },
    "versions": {
      "data": [
        {
          "type": "sla_version",
          "id": "5fadc1ba6647f10a1ef94915"
        },
        {
          "type": "sla_version",
          "id": "5fadc1dd6647f175a7f9491e"
        }
      ]
    }
  }
}
```

Fields:

- `attributes.currentVersion` (integer): The number of the SLA's latest version. Every edit in the admin settings creates a new version, and conversations record the one they matched in `sla.version`.
- `attributes.createdAt` (string): When the SLA was first created. Each version has its own `createdAt`.
- `relationships.versions` (object): Every version of the SLA, as IDs only. Add `versions=active` or `versions=all` to get their names, metrics, targets and criteria in `included`.
- `relationships.versions.data[].id` (string): An SLA version ID. Search conversations matched to a specific version with `conversation_sla_version_id`.

### Permissions

Fewest roles for a read-only integration: `org.permission.sla.read`. For every endpoint: `org.permission.sla.read`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Unique SLA ID. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `versions` | string | no | Option to include information about SLA versions. Use `all` to retrieve information about all versions. Use `active` to retrieve information about the active version only. |

## Responses

### 200

Success

- `data` (object, required)
  - `type` (string, required)
  - `id` (string, required)
  - `attributes` (object, required)
    - `currentVersion` (integer, required)
    - `createdAt` (string, required)
  - `relationships` (object, required)
    - `org` (object, required)
    - `createdBy` (object, required)
    - `versions` (object, required)
- `included` (object, required)
  - `type` (string, required)
  - `id` (string, required)
  - `attributes` (object, required)
    - `name` (string, required)
    - `description` (string, required)
    - `version` (integer, required)
    - `hours` (string, required)
    - `metrics` (object, required)
    - `criteria` (object, required)
    - `createdAt` (string, required)
  - `relationships` (object, required)
    - `org` (object, required)
    - `createdBy` (object, required)
    - `sla` (object, required)

```json
{
  "data": {
    "type": "sla",
    "id": "5fadc1ba6647f1953ff94916",
    "attributes": {
      "currentVersion": 1,
      "createdAt": "2020-11-12T23:14:02.462Z"
    },
    "relationships": {
      "org": {
        "links": {
          "self": "/v1/orgs/5d811e40de762100130174a8"
        },
        "data": {
          "type": "org",
          "id": "5d811e40de762100130174a8"
        }
      },
      "createdBy": {
        "links": {
          "self": "/v1/users/5d811e4f6be8d8001391132c"
        },
        "data": {
          "type": "user",
          "id": "5d811e4f6be8d8001391132c"
        }
      },
      "versions": {
        "data": [
          {
            "type": "sla_version",
            "id": "5fadc1ba6647f10a1ef94915"
          },
          {
            "type": "sla_version",
            "id": "5fadc1dd6647f175a7f9491e"
          }
        ]
      }
    }
  },
  "included": {
    "type": "sla_version",
    "id": "5fadc1dd6647f175a7f9491e",
    "attributes": {
      "name": "Email Policy",
      "description": "SLA policy for email conversations.",
      "version": 1,
      "hours": "calendar",
      "metrics": {
        "firstResponse": {
          "enabled": true,
          "basedOnHumanInteraction": true,
          "times": {
            "1": 3600000,
            "2": 3600000,
            "3": 3600000,
            "4": 3600000,
            "5": 3600000
          }
        },
        "nextReply": {
          "enabled": true,
          "basedOnHumanInteraction": false,
          "times": {
            "1": 7200000,
            "2": 7200000,
            "3": 7200000,
            "4": 7200000,
            "5": 7200000
          }
        },
        "longestUnrespondedMessage": {
          "enabled": true,
          "times": {
            "1": 14400000,
            "2": 14400000,
            "3": 14400000,
            "4": 14400000,
            "5": 14400000
          }
        },
        "totalConversationOpenTime": {
          "enabled": false,
          "times": {}
        },
        "totalCustomerWaitTime": {
          "enabled": false,
          "times": {}
        }
      },
      "criteria": {
        "and": [
          {
            "conversation_channel": {
              "operator": "contains",
              "value": "email"
            }
          }
        ]
      },
      "createdAt": "2020-11-12T23:14:37.406Z"
    },
    "relationships": {
      "org": {
        "links": {
          "self": "/v1/orgs/5d811e40de762100130174a8"
        },
        "data": {
          "type": "org",
          "id": "5d811e40de762100130174a8"
        }
      },
      "createdBy": {
        "links": {
          "self": "/v1/users/5d811e4f6be8d8001391132c"
        },
        "data": {
          "type": "user",
          "id": "5d811e4f6be8d8001391132c"
        }
      },
      "sla": {
        "data": {
          "type": "sla",
          "id": "5fadc1ba6647f1953ff94916"
        },
        "links": {
          "self": "/v1/slas/5fadc1ba6647f1953ff94916"
        }
      }
    }
  }
}
```

### 400

Bad Request

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/slas/5fadc1ba6647f1953ff94916' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```