---
title: "Get expiration schedule"
method: GET
path: "/v1/reports/expiration-schedule"
tags: ["Reporting"]
---

# Get expiration schedule

`GET /v1/reports/expiration-schedule`

## Request

- Base URL: `https://api.scrip.dev`
- URL: `https://api.scrip.dev/v1/reports/expiration-schedule`
- Auth: HTTP bearer

Returns when outstanding lot-mode liability expires, in calendar-aligned buckets by asset and program. LOT-mode assets only.
This report does not accept created_after or created_before.

## Query parameters

- `period_start` string, date-time, required
- `period_end` string, date-time, required
- `granularity` 'day' | 'week' | 'month'
- `program_id` string, uuid
- `asset_id` string, uuid

## Response `200`

Expiration schedule

- ExpirationScheduleListResponse: Expiration schedule results
  - `data` ExpirationScheduleAssetResponse[]: One expiration schedule per LOT inventory-mode asset
    - `asset_id` string, uuid: Unique identifier for this asset
    - `asset_name` string: The name people see for the asset, such as `Points`.
    - `asset_symbol` string: Ticker or symbol for this asset (e.g., `POINTS`)
    - `attribution_adjustment` string: Adjustment for the difference between the program that issued the lots and the program recorded on ledger entries. Added after subtracting the overdraft; may be positive or negative. Zero for organization-wide results.
    - `buckets` ExpirationScheduleBucketResponse[]: Calendar buckets inside the window that have expiring value, ordered by bucket_start. A bucket with nothing expiring does not appear.
      - `amount` string: Outstanding lot value expiring in this bucket
      - `bucket_end` string: Bucket end (exclusive): start plus one granularity unit
      - `bucket_start` string: Bucket start (inclusive, UTC, at the start of a calendar day, week or month)
      - `lot_count` integer: Number of lots contributing to this bucket
    - `expiring_after_window` string: Outstanding value on lots expiring after the window end
    - `expiring_before_window` string: Outstanding value on lots expiring before the window start, including lots already past expires_at that the breakage sweep has not yet forfeited
    - `gross_lot_outstanding` string: Gross remaining participant/group lot value before LOT overdraft netting. Reconciles as never_expiring + expiring_before_window + expiring_after_window + sum(buckets[].amount).
    - `never_expiring` string: Outstanding value on lots with no expiration date
    - `overdraft_offset` string: Uncovered LOT-mode DEBIT value subtracted from gross_lot_outstanding. Always non-negative; positive values are overdraft debt.
    - `scale` integer: Decimal scale amounts are formatted with
    - `total_outstanding` string: Outstanding liability calculated from ledger entries for this asset. Equals `gross_lot_outstanding - overdraft_offset + attribution_adjustment`.
  - `pagination` PaginationResponse: Cursor details for a list. `has_more` says whether another page exists, and `next_cursor` is the value to send to get it.
    - `has_more` boolean, required: Whether more results are available beyond this page
    - `next_cursor` string, nullable, required: Cursor to fetch the next page. Null on the last page

## Other responses

- `400`: Invalid query parameters or SIMPLE-mode asset_id (code: validation_error)
- `401`: The API key is missing or not valid. See [Authentication](https://docs.scrip.dev/authentication).
- `404`: Asset not found (code: asset_not_found)
- `429`: Too many requests. Wait the number of seconds in the `Retry-After` header, then retry. See [Limits and durations](https://docs.scrip.dev/limits#rate-limits).
- `500`: Something failed on Scrip's side. Retry the request, and quote `request_id` if it keeps failing. [Errors](https://docs.scrip.dev/errors) lists every code, and the [API introduction](https://docs.scrip.dev/api-reference/introduction) describes the error format.

---

[API](https://skmtc.dev/scrip/apis/scrip-api.md) · [All operations](https://skmtc.dev/scrip/apis/scrip-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrip/apis/scrip-api/revisions/c52d35da8d97?raw)