---
title: "List Obligation Instances"
method: GET
path: "/obligations/{id}/instances"
tags: ["Obligations"]
---

# List Obligation Instances

`GET /obligations/{id}/instances`

## Request

- Base URL: `https://ironcladapp.com/public/api/v1`
- URL: `https://ironcladapp.com/public/api/v1/obligations/{id}/instances`
- Auth: API key in header `Authorization` and OAuth 2
  - Authorization code: `https://ironcladapp.com/oauth/authorize`
  - Client credentials
  - Token URL: `https://ironcladapp.com/oauth/token` scopes: `public.obligations.readObligations`

List the instances (occurrences) of a source obligation, ordered by due date with undated instances last. Every item has `obligationType` `OCCURRENCE`. Recurring occurrences are generated automatically by Ironclad; triggered occurrences are recorded with Create an Obligation. Requires triggered obligations to be enabled for your account.

**OAuth Scope required:** `public.obligations.readObligations`

## Path parameters

- `id` string, required

## Query parameters

- `page` integer
- `pageSize` integer

## Headers

- `x-as-user-email` string
- `x-as-user-id` string

## Response `200`

200

- object
  - `page` integer: The zero-based page number for paginating through results
  - `pageSize` integer: The number of items to return per page
  - `count` integer: The total number of instances of the source obligation across all pages
  - `list` ObligationModel[]
    - `id` string, required: The unique identifier of the obligation
    - `ironcladId` string, required: Readable Ironclad ID of the obligation
    - `name` string, required: The name of the obligation
    - `properties` RecordProperties, required: The record properties associated with the record
    - `lastUpdated` string: The last updated date of the obligation
    - `namedTypeIds` string[]: The unique identifiers of the types associated with the obligation. These IDs are tied with the Named Type of obligations, like 'Breach Notice', 'Compliance' and so on.
    - `parentReadableId` string: The parent readable id of the obligation
    - `parentRecordName` string: The parent record name of the obligation
    - `isActive` boolean: Whether the user-facing obligation is active. Occurrences inherit their source obligation's active state. Read-only and present when the obligation lifecycle feature is enabled.
    - `status` 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED' | 'WAIVED' | 'CANCELLED' | 'COMPLIANT' | 'NON_COMPLIANT': The status of the obligation.
    - `description` string: Human-readable description of the obligation.
    - `dueDate` string: The due date of the obligation (yyyy-MM-dd).
    - `assigneeUserId` string: The ID of the user assigned to the obligation.
    - `completedAt` string, date-time: The ISO 8601 timestamp at which the obligation entered the COMPLETED status. Present only while the obligation is COMPLETED.
    - `sourceObligationId` string, uuid: The ID of the source obligation.
    - `sourceRelationshipType` 'RECURRING' | 'TRIGGERED': How the source obligation is related. `RECURRING` for obligations created by a recurring trigger, `TRIGGERED` for obligations created by a condition. Only present on obligations with a source (has a `sourceObligationId`).
    - `triggerSource` 'API' | 'MANUAL': The originating source of a triggered obligation. `API` when created through the public API, `MANUAL` when created in-product. Only present on obligations with a `sourceRelationshipType` of `TRIGGERED`.
    - `obligationType` 'SOURCE' | 'OCCURRENCE': Distinguishes a source obligation from an occurrence. `SOURCE` obligations carry a `cadence`; `OCCURRENCE` obligations carry a `sourceObligationId` and `sourceRelationshipType`. Read-only.
    - `cadence` 'ONE_TIME' | 'RECURRING' | 'TRIGGERED' | 'PERPETUAL': The recurrence cadence of a source obligation. Only present on `SOURCE` obligations. Read-only; not accepted on create or update.

## Other responses

- `400`: 400
- `401`: 401
- `403`: 403
- `404`: 404

## Changes

- **2026-11-03** `435da5a4396e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/changes/obligations/:id/instances/get.md)

---

[API](https://skmtc.dev/ironcladapp/apis/ironclad-public-api.md) - [All operations](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/revisions/435da5a4396e?raw)