---
title: "Business days between two dates, or the date N business days from a date"
method: GET
path: "/api/v1/business-days"
---

# Business days between two dates, or the date N business days from a date

`GET /api/v1/business-days`

## Request

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

Span mode: from + to. Add mode: date (default today) + days (+ dir=from|before). Both modes accept cal (jurisdiction), custom (comma-separated ISO dates, mutually exclusive with cal), ww (workweek: mon-fri, sun-thu, mon-sat), tz. When a holiday calendar is in play (cal or custom), the span between from and to is limited to 100000 days; resolving a jurisdiction's rules is per-year work, so a centuries-wide holiday span is refused with out_of_range. Without a calendar the full 1600-3000 year range is accepted.

## Query parameters

- `from` string: Strict ISO YYYY-MM-DD, or the literal "today" (resolved in tz).
- `to` string: Strict ISO YYYY-MM-DD, or the literal "today" (resolved in tz).
- `date` string: Strict ISO YYYY-MM-DD, or the literal "today" (resolved in tz).
- `days` integer
- `dir` 'from' | 'before'
- `cal` 'US' | 'GB' | 'GB-SCT' | 'GB-NIR' | 'CA' | 'AU' | 'UG' | 'UK': Holiday jurisdiction (ISO 3166-1/-2; UK is a legacy alias for GB).
- `custom` string
- `ww` 'mon-fri' | 'sun-thu' | 'mon-sat'
- `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)