# Answer each date in a window

> Premium.

Source: https://api.tailend.dev/docs/api/get-school-calendar-days

```http
GET https://api.tailend.dev/v1/{metro}/school-calendars/{district}/days
X-API-Key: $TAILEND_API_KEY
```

Premium. One answer for every date from `from` to `to` inclusive,
weekends included, in date order. `from` and `to` are required and the
window is at most 366 days.

Each day has a `type` (`school`, `no_school`, `half_day`, `break` or
`summer`) and a `reason`. **Every stated date carries a `source`**:
the page we read it from, the exact wording quoted from it, and when
we last checked it. Days that follow from the calendar rather than
being named in it (weekends, ordinary school days between stated
dates, summer) have `source: null`; unavailable days do too. `basis` says whether the answer is `stated`
outright by the district, `implied` (for example a school day between
stated dates), or `unknown`.

**Unavailable is not summer.** When we cannot answer a date, `type`,
`is_school_day` and `source` are `null`, `basis` is `unknown` and
`reason` starts with `unavailable_`. Treat that as "we do not know",
never as a closure. `summer` is only returned between a calendar's
last day and the next first day or, when the next school year is not
published yet, up to 31 July. After that the date is unavailable. A district with no published calendar
for the window returns 200 with every date unavailable and `edition:
null`.

**Grades.** Without `grade`, a date is `school` only if it is a school
day for every grade. Where grades get different answers the day also
carries `by_grade`, grouping grades that share an answer. With
`grade`, the top-level answer is that grade's, and `by_grade` is
omitted. Asking for a grade the district does not serve is a 400.

Dates are the metro's local calendar dates. Snow days and other
emergency closures are not covered. See
[School calendars](https://api.tailend.dev/docs/school-calendars.md).

Authorization: send your key in the `X-API-Key` header. Requires the partner plan or a key entitled to it. See Plans & access.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `metro` | string | yes | Metro slug from /v1/metros (e.g. philadelphia). |
| `district` | string | yes | District slug from /v1/{metro}/school-calendars. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string (date) | yes | First date, inclusive (YYYY-MM-DD, the metro's local date). |
| `to` | string (date) | yes | Last date, inclusive (YYYY-MM-DD). |
| `grade` | string | no | Answer for one grade. |

## Example request

```bash
curl -sS \
  -H "X-API-Key: $TAILEND_API_KEY" \
  "https://api.tailend.dev/v1/philadelphia/school-calendars/example-school-district/days?from=2026-10-01&to=2026-10-31"
```

## Responses

### 200

One answer per date in the window

```json
{
  "data": [
    {
      "date": "2026-11-26",
      "type": "no_school",
      "reason": "holiday",
      "label": "Thanksgiving recess",
      "is_school_day": false,
      "basis": "stated",
      "source": {
        "url": "https://www.example.org/calendar",
        "quote": "Thanksgiving recess, November 26-27",
        "verified_at": "2026-10-01T12:00:00Z"
      }
    },
    {
      "date": "2026-11-27",
      "type": "no_school",
      "reason": "holiday",
      "label": "Thanksgiving recess",
      "is_school_day": false,
      "basis": "stated",
      "source": {
        "url": "https://www.example.org/calendar",
        "quote": "Thanksgiving recess, November 26-27",
        "verified_at": "2026-10-01T12:00:00Z"
      }
    },
    {
      "date": "2026-11-28",
      "type": "no_school",
      "reason": "weekend",
      "label": null,
      "is_school_day": false,
      "basis": "implied",
      "source": null
    }
  ],
  "edition": {
    "school_year": "2026-27",
    "published_at": "2026-07-15T14:00:00Z",
    "board_approved_on": "2026-06-18"
  },
  "meta": {
    "metro": "philadelphia",
    "district": "example-school-district",
    "from": "2026-11-26",
    "to": "2026-11-28",
    "count": 3,
    "unavailable_count": 0
  }
}
```

### 400

Malformed or contradictory parameters (lat without lng, to before from, unknown category), or a cursor this API did not issue for this exact request — replayed from another endpoint, resource, metro or filter set, hand-crafted, or altered.

```json
{
  "error": {
    "code": "bad_request",
    "message": "radius_m: must be at least 100",
    "details": {
      "param": "radius_m"
    },
    "request_id": "req_dfbc3295a8382b05"
  }
}
```

### 401

Missing, unknown or revoked X-API-Key.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "missing X-API-Key header",
    "request_id": "req_90e63908273f6bff"
  }
}
```

### 403

Two different reasons share this status.

```json
{
  "error": {
    "code": "forbidden",
    "message": "key is not scoped to metro 'boston'",
    "details": {
      "metros": [
        "philadelphia"
      ]
    },
    "request_id": "req_9e7a750acef48ab2"
  }
}
```

### 404

No published, active resource with that id (or unknown metro).

```json
{
  "error": {
    "code": "not_found",
    "message": "unknown metro 'boston'",
    "request_id": "req_7431b51e10ec2b77"
  }
}
```

### 405

The path exists; the method does not.

```json
{
  "error": {
    "code": "method_not_allowed",
    "message": "POST is not allowed on this path; this API is read-only",
    "details": {
      "allow": [
        "GET",
        "HEAD",
        "OPTIONS"
      ]
    },
    "request_id": "req_01J9Z3"
  }
}
```

### 429

A limit was reached.

```json
{
  "error": {
    "code": "rate_limited",
    "message": "3 requests per minute exceeded",
    "request_id": "req_06bfd3c2d5e8aa9f"
  }
}
```

### 500

A bug on our side.

```json
{
  "error": {
    "code": "internal",
    "message": "internal error",
    "request_id": "req_01J9Z3"
  }
}
```

### 501

This endpoint or feature is not available and will not become available without a configuration change — for ?address=, this means no geocoder is configured.

```json
{
  "error": {
    "code": "not_implemented",
    "message": "this endpoint is not enabled on this deployment; it is not a fault and retrying will not help",
    "request_id": "req_01J9Z3"
  }
}
```

### 503

A transient outage: a dependency could not be reached or did not answer in time.

```json
{
  "error": {
    "code": "unavailable",
    "message": "the service is temporarily unable to serve this request; retry after the interval in Retry-After",
    "request_id": "req_01J9Z3"
  }
}
```
