# Retrieve metro coverage

> Returns coverage as a buyer would judge it for a metro: live counts by type, how far ahead events run, how much of what is currently served is confirmed current, and how many rows carry an organization, neighborhood, place or coordinates.

Source: https://api.tailend.dev/docs/api/get-metro-coverage

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

Returns coverage as a buyer would judge it for a metro: live counts by
type, how far ahead events run, how much of what is currently served
is confirmed current, and how many rows carry an organization,
neighborhood, place or coordinates.

Numbers are computed from the same rows the collection endpoints
serve. Responses may be cached according to `Cache-Control`;
every key entitled to the metro sees the same report. Returns 501
when this endpoint is unavailable.

Authorization: send your key in the `X-API-Key` header. Available on every plan.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `metro` | string | yes | Metro slug from /v1/metros (e.g. philadelphia). |

## Example request

```bash
curl -sS \
  -H "X-API-Key: $TAILEND_API_KEY" \
  "https://api.tailend.dev/v1/philadelphia/coverage"
```

## Responses

### 200

The report

```json
{
  "data": {
    "metro": "philadelphia",
    "timezone": "America/New_York",
    "counts": {
      "event": 1583,
      "class": 648,
      "camp": 88,
      "place": 983,
      "ongoing": 16
    },
    "events": {
      "future": 950,
      "next_7_days": 165,
      "next_30_days": 500,
      "future_recurring": 460,
      "horizon": "2027-06-01T00:00:00Z"
    },
    "freshness": {
      "confirmed_last_7d_pct": 62.3,
      "confirmed_last_30d_pct": 84.1,
      "upcoming_48h_confirmed_12h_pct": 58,
      "median_source_age_days": 8.8
    },
    "fields": {
      "total": 2335,
      "with_organization": 2167,
      "with_neighborhood": 1380,
      "with_place": 1823,
      "with_coordinates": 1340
    },
    "organizations": 357,
    "sources": {
      "total": 357
    },
    "generated_at": "2026-09-13T12:00:00Z"
  }
}
```

### 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"
  }
}
```