> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Deadlines

> List computed maintenance deadlines for a portfolio or trademark

Supply exactly one of `portfolio_id` or `trademark_id`. Every request requires
`trademarks:read`; a `portfolio_id` request additionally requires
`portfolios:manage`, and a key missing either scope gets 403 `forbidden`.
Portfolio requests return 404 for a portfolio outside your organization.
Trademark requests accept any retrievable mark.
Each page costs **one read unit**, with a default of 20 and a maximum of 100 rows.

Deadlines are computed when requested. Rows carry `rule_id`, `effective_from`,
`last_verified`, `sources[]`, `trigger_date`, and `trigger_field`, alongside
trademark identity, due date, window opening, grace expiry and urgency.
`sources[]` holds the statutory citations behind the rule, the same ones
[Compute Deadlines](/api-reference/reference/compute-deadlines) returns; join
`rule_id` to [List Deadline Rules](/api-reference/reference/deadline-rules) for
the full rule record. For prosecution deadlines, use
[Compute Deadlines](/api-reference/reference/compute-deadlines).

Filter with a comma-separated `type`, an inclusive `due_before` date (`YYYY-MM-DD`),
or `urgency` (`critical`, `upcoming`, `routine`, `in_grace`, `missed`). The list is
forward-looking by default and omits deadlines whose grace period has already
closed; `urgency=missed` selects exactly those rows instead.
The default cutoff is 720 days after the computation date, within a five-year
computation horizon. Portfolios are capped at 5,000 marks; split larger portfolios.

Results sort by `due_date`, `trademark_id`, then `rule_id`, all ascending. Follow
`pagination.cursor` while `has_more` is true. The signed cursor pins the computation
date and binds the selector and filters. Keep those parameters unchanged on the
next page. A cursor that fails to decode or verify — malformed, unsigned, minted
for another endpoint, or an old offset cursor — returns `400 cursor_expired`; a
cursor that verifies but whose selector or filters have changed returns
`400 cursor_invalid`. Either way, restart at page one. Records and portfolio
membership may change between pages: the cursor pins the clock, not a historical
snapshot.

`GET /v1/portfolios/{id}/deadlines` is an alias using the same rows, filters and
cursor. Both paths preserve the portfolio list's inclusive cutoff semantics, and
a cursor minted on one can be followed on the other. The alias differs in one
deliberate way: it requires `portfolios:manage` alone, without the base
`trademarks:read` this path also requires, because its scope is unchanged from
the day it shipped and adding a required scope to a published operation would
break existing keys.

```typescript theme={null}
const deadlines = await signa.deadlines.list({
  portfolio_id: 'ptf_12345678-1234-1234-1234-123456789012',
  type: ['renewal', 'international_renewal'],
  limit: 100,
});
for await (const deadline of deadlines) {
  console.log(deadline.trademark_id, deadline.due_date, deadline.rule_id);
}
```

A single row looks like this:

```json theme={null}
{
  "trademark_id": "tm_019d2141-6ce9-771b-872e-bc8b20e49fcf",
  "rule_id": "us_declaration_of_use_s8",
  "effective_from": null,
  "last_verified": "2026-03-10",
  "mark_text": "EXAMPLE",
  "office_code": "US",
  "type": "declaration_of_use",
  "due_date": "2026-03-10",
  "grace_expiry": "2026-09-10",
  "window_opens": "2025-03-10",
  "jurisdiction_code": "US",
  "description": "Declaration of Use (Section 8)",
  "trigger_date": "2020-03-10",
  "trigger_field": "registration_date",
  "urgency": "upcoming",
  "sources": [
    {
      "citation": "15 U.S.C. § 1058(a) — registration term and affidavit requirement",
      "url": "https://www.law.cornell.edu/uscode/text/15/1058"
    }
  ]
}
```