# List organizations

> Returns every organization with at least one published, active listing in the metro, with live counts by type.

Source: https://api.tailend.dev/docs/api/list-organizations

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

Returns every organization with at least one published, active listing in
the metro, with live counts by type. Without `q`, ordered by `name` then
`id`, keyset-paged like the collections; the cursor is bound to `q` and
`type`.

**Finding a business.** Send `q` to look one up by what a person would
type: its name, its website address (`designgym.com`), or a pasted URL
(`https://www.designgym.com/classes`). Casing, punctuation and spacing
are ignored, as are endings such as `LLC`, `Inc`, `The`, `& Co` and
`.com`/`.co`/`.org`/`.net`/`.io`/`.us`, and `design gym` finds
`designgym`. A small typo (`desing gym`) still finds it. Both the
organization's name and its website addresses are searched, whether or
not `website_url` is filled in.

With `q`, every result carries `score` and `match`, and results are
ordered by `score` (highest first), then `name`, then `id`. `score` is
0 to 1, higher is closer, and is the same for one organization
whatever else is returned, so it can be shown as a confidence.
`match` says how it was found: `exact_name` or `exact_domain` (the
whole name or address was typed), `name` or `domain` (the same words
once spelling, spacing and endings are set aside, or the start or a
word of the name), or `fuzzy` (a small typo away). A `domain` match on a
different ending (`acme.org` for `acme.com`) is a suggestion to
confirm. Pages on shared platforms (social pages, booking widgets,
website builders) are never `exact_domain`. A `q` made only of words
like `the` or `and`, or of endings like `llc` or `.com`, returns an
empty list with `meta.hint`. `page`, `limit` and `cursor` work as usual;
a cursor follows the same ranked order.

`website_url` is the organization's own website. When none is recorded
it is the address of the site the organization itself runs, if we
have one, and stays `null` when there is nothing trustworthy to show.

Returns 501 when this endpoint is unavailable. Organization detail with
its metros list is at `/v1/organizations/{id}`; listings themselves are
the collections filtered with `organization_id=`.

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). |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | no | Find a business by what a person would type: its name, its website address or a pasted URL. |
| `type` | string | no | Exact match on the organization's type. |
| `cursor` | string | no | Opaque cursor from meta.next_cursor. |
| `page` | integer | no | 1-based page number (browse mode). |
| `limit` | integer | no |  |

## Example request

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

## Responses

### 200

OK

```json
{
  "data": [
    {
      "id": "c6e39d31-abce-43f8-bccd-2cf5ce73a0ad",
      "name": "Philadelphia School of Circus Arts",
      "slug": "philadelphia-school-of-circus-arts",
      "organization_type": "recreation",
      "website_url": "https://phillycircus.com",
      "city": "Philadelphia",
      "state": "PA",
      "is_verified": false,
      "links": {
        "self": "/v1/organizations/c6e39d31-abce-43f8-bccd-2cf5ce73a0ad",
        "events": "/v1/organizations/c6e39d31-abce-43f8-bccd-2cf5ce73a0ad/events",
        "classes": "/v1/organizations/c6e39d31-abce-43f8-bccd-2cf5ce73a0ad/classes",
        "camps": "/v1/organizations/c6e39d31-abce-43f8-bccd-2cf5ce73a0ad/camps",
        "places": "/v1/organizations/c6e39d31-abce-43f8-bccd-2cf5ce73a0ad/places"
      },
      "metro": "philadelphia",
      "live": {
        "listings": 19,
        "events": 4,
        "classes": 11,
        "camps": 4,
        "places": 0
      },
      "updated_at": "2026-09-26T13:45:37.633Z"
    }
  ],
  "meta": {
    "metro": "example",
    "limit": 1,
    "count": 1,
    "has_more": false
  }
}
```

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