---
title: "List tenants"
method: GET
path: "/tenants"
tags: ["Tenants"]
---

# List tenants

`GET /tenants`

## Request

- Base URL: `https://api.groundmail.dev`
- URL: `https://api.groundmail.dev/tenants`
- Auth: HTTP bearer

Tenants are your own customers inside one Groundmail account, each with its own domains, suppression list, stats, sending ramp and pause switch. Included on the Scale (up to 1,000 tenants) and Dedicated (up to 10,000) plans; other plans get 403 `tenants_not_enabled`.

## Query parameters

- `status` 'active' | 'paused'
- `limit` integer
- `cursor` string

## Response `200`

A page of tenants

- ListTenantsResponse
  - `data` Tenant[], required
    - `id` string, uuid, required
    - `object` 'tenant', required
    - `external_id` string, required
    - `name` string, required
    - `status` 'active' | 'paused', required
    - `paused_reason` string, nullable
    - `paused_at` string, date-time, nullable
    - `pause_source` 'api' | 'admin' | 'automated' | 'null', nullable: Who paused the tenant: `api` (you), `automated` (Groundmail, after a high bounce or complaint rate) or `admin` (Groundmail support).
    - `default_from_domain` string, nullable
    - `stream_policy` 'all' | 'transactional_only', required
    - `daily_limit` integer, nullable
    - `metadata` object, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required

## Other responses

- `401`: Missing or invalid API key
- `403`: Tenants are not included on this account's plan (`tenants_not_enabled`), or the key is not full access or is limited to one tenant

---

[API](https://skmtc.dev/groundmail/apis/groundmail-api.md) · [All operations](https://skmtc.dev/groundmail/apis/groundmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/groundmail/apis/groundmail-api/revisions/479821c9fecf?raw)