> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hadoseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Domains

> List every domain on your account with its ID, origin URL, and role

```
POST /functions/v1/list-user-domains
```

Returns basic metadata for **every domain your account can access** — both domains you own and domains [shared](/dashboard/analytics) with you. Use it to discover each domain's `domainId`, which you can then pass to [Export Analytics](/api-reference/endpoint/export-analytics) to pull a single domain's data.

<Warning>
  Always call this endpoint from a **server-side environment** (backend API, serverless function, build script, etc.). Never include your API key in client-side code — it will be visible to anyone inspecting your frontend.
</Warning>

<Info>
  Programmatic (API key) access requires the **Pro plan and above** — requests
  from Starter accounts return `403 plan_upgrade_required`.
</Info>

## Request

### Headers

| Header          | Required | Description                    |
| --------------- | -------- | ------------------------------ |
| `Authorization` | Yes      | `Bearer hado_sk_your_key_here` |
| `Content-Type`  | Yes      | `application/json`             |

### Body Parameters

None. The endpoint always returns every domain your account can access.

### Example Request

```bash theme={null}
curl -X POST https://api.hadoseo.com/functions/v1/list-user-domains \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -H "Content-Type: application/json"
```

## Response

### Success (200)

```json theme={null}
{
  "userId": "00000000-0000-0000-0000-000000000000",
  "domainCount": 2,
  "domains": [
    {
      "domainId": "11111111-1111-1111-1111-111111111111",
      "domain": "example.com",
      "originUrl": "https://example.lovable.app",
      "role": "owner",
      "verificationStage": "verified",
      "createdAt": "2026-01-14T09:32:00.000Z"
    },
    {
      "domainId": "22222222-2222-2222-2222-222222222222",
      "domain": "client.dev",
      "originUrl": "https://client.lovable.app",
      "role": "manager",
      "verificationStage": "verified",
      "createdAt": "2026-03-02T15:10:00.000Z"
    }
  ]
}
```

### Fields

| Field                         | Type           | Description                                                                                                      |
| ----------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `userId`                      | string         | The account that owns the API key.                                                                               |
| `domainCount`                 | number         | Number of domains returned.                                                                                      |
| `domains[].domainId`          | string         | The domain's unique ID. Pass this to [Export Analytics](/api-reference/endpoint/export-analytics) as `domainId`. |
| `domains[].domain`            | string         | The domain hostname (e.g. `example.com`).                                                                        |
| `domains[].originUrl`         | string \| null | The origin/app URL the domain proxies to.                                                                        |
| `domains[].role`              | string         | Your access level for this domain: `owner`, `manager`, or `viewer`.                                              |
| `domains[].verificationStage` | string \| null | Where the domain is in verification (e.g. `pending`, `verified`).                                                |
| `domains[].createdAt`         | string \| null | ISO 8601 timestamp of when the domain was added.                                                                 |

Domains are sorted alphabetically by hostname. When a domain is both owned and shared with you, it appears once with the `owner` role.

### Error Responses

| Status | Body                                                             | Description                                        |
| ------ | ---------------------------------------------------------------- | -------------------------------------------------- |
| 401    | `{ "error": "invalid_api_key" }`                                 | API key is missing, invalid, or revoked            |
| 403    | `{ "error": "plan_upgrade_required" }`                           | Programmatic access requires the Pro plan or above |
| 429    | `{ "error": "rate_limit_exceeded", "usage": 300, "limit": 300 }` | Monthly or per-minute rate limit exceeded          |

<Info>
  When you receive a **429**, the `usage` and `limit` fields tell you where you stand against your monthly quota. Per-minute limits (60 req/min) reset automatically after 60 seconds. See [Authentication](/api-reference/authentication) for plan limits.
</Info>

## Examples

### JavaScript / Node.js

Enumerate domains, then export each one individually:

```javascript theme={null}
const HEADERS = {
  "Authorization": `Bearer ${process.env.HADOSEO_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. List every domain on the account.
const listRes = await fetch(
  "https://api.hadoseo.com/functions/v1/list-user-domains",
  { method: "POST", headers: HEADERS },
);
const { domains } = await listRes.json();

// 2. Export each domain separately.
for (const { domainId, domain } of domains) {
  const res = await fetch(
    "https://api.hadoseo.com/functions/v1/export-user-analytics",
    {
      method: "POST",
      headers: HEADERS,
      body: JSON.stringify({ domainId, period: "30d" }),
    },
  );
  const report = await res.json();
  console.log(domain, report.domains[0]?.botTotals);
}
```