# Retrieve a district's stated calendar

> Premium.

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

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

Premium. The calendar as the district states it for one school year:
a list of dated entries, so a client can draw the year without
requesting every day. Each entry is a date or date range with a type,
a reason, the district's own label, the grades it applies to and
where it was stated. Entries are in date order.

`school_year` defaults to the school year containing today in the
metro. When we hold no published calendar for that year, `edition` is
`null` and `entries` is empty; that is not a statement that school is
out. Use [`/days`](#operation/getSchoolCalendarDays) for a per-date
answer, including dates we cannot answer.

`grades: null` means the entry applies to all students.

District policies are not served yet: `policies` is always an empty
array and `meta.policy_count` is `0`. The field is reserved.

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 |
| --- | --- | --- | --- |
| `school_year` | string | no | School year as YYYY-YY with consecutive years (2026-27; 2026-28 is a 400). |

## Example request

```bash
curl -sS \
  -H "X-API-Key: $TAILEND_API_KEY" \
  "https://api.tailend.dev/v1/philadelphia/school-calendars/%5Bobject%20Object%5D"
```

## Responses

### 200

The stated calendar for the school year

```json
{
  "data": {
    "district": {
      "slug": "example-school-district",
      "name": "Example School District",
      "state": "PA",
      "website_url": "https://www.example.org"
    },
    "school_year": "2026-27",
    "edition": {
      "school_year": "2026-27",
      "published_at": "2026-07-15T14:00:00Z",
      "board_approved_on": "2026-06-18"
    },
    "entries": [
      {
        "starts_on": "2026-08-31",
        "ends_on": "2026-08-31",
        "type": "school",
        "reason": "first_day",
        "label": "First day for students",
        "grades": null,
        "source": {
          "url": "https://www.example.org/calendar",
          "quote": "First day for students, Monday, August 31",
          "verified_at": "2026-10-01T12:00:00Z"
        }
      },
      {
        "starts_on": "2026-11-26",
        "ends_on": "2026-11-27",
        "type": "no_school",
        "reason": "holiday",
        "label": "Thanksgiving recess",
        "grades": null,
        "source": {
          "url": "https://www.example.org/calendar",
          "quote": "Thanksgiving recess, November 26-27",
          "verified_at": "2026-10-01T12:00:00Z"
        }
      }
    ],
    "policies": []
  },
  "meta": {
    "metro": "philadelphia",
    "district": "example-school-district",
    "school_year": "2026-27",
    "entry_count": 2,
    "policy_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"
  }
}
```
