---
title: "Date N calendar days before a date"
method: GET
path: "/api/v1/subtract"
---

# Date N calendar days before a date

`GET /api/v1/subtract`

## Request

- Base URL: `https://tilwhen.com`
- URL: `https://tilwhen.com/api/v1/subtract`
- Auth: none declared

## Query parameters

- `date` string: Strict ISO YYYY-MM-DD, or the literal "today" (resolved in tz).
- `days` integer, required
- `tz` string: IANA timezone name; defaults to UTC.

## Response `200`

The answer plus its auditable receipt

- object
  - `answer` object, required
  - `receipt` Receipt, required: Auditable calculation record; field order in serialized responses is stable.
    - `id` string
    - `query` object
    - `resolved` object
    - `answer` object
    - `timezone` string
    - `convention` 'exclusive-today-is-day-0'
    - `workweek` 'mon-fri' | 'sun-thu' | 'mon-sat'
    - `jurisdiction` string, nullable
    - `customHolidays` string[]
    - `holidaysExcluded` object[]: Itemised excluded holidays, capped at 500; see holidaysExcludedCount for the true total.
      - `name` string
      - `dateISO` string
    - `holidaysExcludedCount` integer: Total holidays excluded by the calculation. Exceeds holidaysExcluded.length on very wide spans, where a holiday_list_truncated warning also appears.
    - `computedAt` string, date-time
    - `validFor` string, date
    - `engineVersion` string
    - `holidayDatasetVersion` string
    - `warnings` object[]
      - `code` string
      - `message` string
    - `sources` object[]
      - `title` string
      - `url` string
      - `publisher` string
      - `retrievedAt` string

## Other responses

- `400`: Machine-readable error
- `429`: Rate limited. The API is free and unauthenticated, so requests are metered per IP at 300 per 60 seconds. Counters are per Cloudflare location and eventually consistent, so this is an abuse brake rather than an exact quota. Retry-After gives the window.

---

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