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

# list_companies

> List companies tracked in your Space. Returns one row per company with id, domain, and external_id.

Returns a cursor-paginated list of companies tracked in your Space. Useful for high-level rollups of which organizations are in your workspace. Each row includes `id`, `domain`, and `external_id`. `domain` is `null` for companies identified only by a customer-supplied `external_id` rather than an email domain; `external_id` is `null` when the customer never supplied one.

## When to use

* *"What companies do we have?"*
* *"List companies added this month."*
* *"How many distinct companies signed up last week?"*

For per-person questions, use [`list_contacts`](https://docs.cometly.com/mcp/tools/list-contacts). For ad performance, use [`query_ad_metrics`](https://docs.cometly.com/mcp/tools/query-ad-metrics).

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `start_date` | string | Conditional | Optional. If set, `end_date` is required. `YYYY-MM-DD HH:MM:SS`, interpreted in your Space's timezone. Filters by company creation date. |
| `end_date` | string | Conditional | Required if `start_date` is set. |
| `per_page` | integer | No | 1–5000. Default 200. |
| `cursor` | string | No | Pagination cursor from a prior response's `next_cursor`. |

## Example response

```json theme={null}
{
  "data": [
    { "id": 1041, "domain": "acme.com", "external_id": null },
    { "id": 1040, "domain": "globex.com", "external_id": null },
    { "id": 1039, "domain": null, "external_id": "acct_8f3k2" }
  ],
  "next_cursor": "eyJpZCI6MTAzOX0",
  "prev_cursor": null,
  "per_page": 200
}
```

## Caveats

* **Companies don't have custom fields** — they're derived from contact email domain or external ID. There's no `custom_field_filters` parameter on this tool today.
* **`domain` can be `null`** — for a company identified only by a customer-supplied `external_id` rather than an email domain. Refer to those companies by their `external_id`, or by ID if that's null too.
* **`external_id` can be `null`** — for a company identified only by an email domain. It's `null` unless the customer explicitly set one via [Update Company](https://docs.cometly.com/api-reference/endpoint/update-company.md) or events carrying `company_external_id`.
* **`name` is not included** in the list view — use [`get_company`](https://docs.cometly.com/mcp/tools/get-company) to retrieve it.
* **Order is newest first** by `id` descending.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.