> ## 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

> Retrieve a paginated list of companies with optional date filtering

## Overview

This endpoint allows you to retrieve a list of companies from Cometly. Results are cursor-paginated for efficient data retrieval and ordered by creation date (newest first).

## Query Parameters

### Optional Parameters

**per\_page** `integer` (default: 200)

Number of companies to return per page. Minimum: 1, Maximum: 5000

**cursor** `string`

Pagination cursor from a previous response. Use this to fetch the next page of results.

**start\_date** `string`

Filter companies created on or after this date. Format: `YYYY-MM-DD HH:MM:SS`. The timestamp is interpreted in your space's timezone.
Example: `2024-01-01 00:00:00`

**end\_date** `string`

Filter companies created on or before this date. Format: `YYYY-MM-DD HH:MM:SS`. Must be after start\_date. The timestamp is interpreted in your space's timezone.
Example: `2024-01-31 23:59:59`

## Response

### Success Response

The response follows Laravel's cursor pagination structure:

**data** `array`

Array of company objects. Each company includes:

* `id` (string): The unique identifier of the company
* `domain` (string | null): The domain associated with this company. `null` if the company was created from a customer-supplied external ID with no associated email domain, or if its domain claim was later released via [Update Company](https://docs.cometly.com/api-reference/endpoint/update-company.md).
* `external_id` (string | null): The customer-supplied external ID associated with this company (your own account/company identifier). `null` if the company was created from an email domain alone, or if its external ID claim was later released via [Update Company](https://docs.cometly.com/api-reference/endpoint/update-company.md).

**path** `string`

The base URL path for the endpoint

**per\_page** `integer`

Number of items per page

**next\_cursor** `string | null`

Cursor for the next page of results. `null` if there are no more pages.

**next\_page\_url** `string | null`

Full URL for the next page of results. `null` if there are no more pages.

**prev\_cursor** `string | null`

Cursor for the previous page of results. `null` if on the first page.

**prev\_page\_url** `string | null`

Full URL for the previous page of results. `null` if on the first page.

### Error Response

**message** `string`

Error description explaining what went wrong

## Example Requests

```bash cURL theme={null}
# Basic request without filters
curl -G "https://app.cometly.com/public-api/v1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

# Request with date filtering
curl -G "https://app.cometly.com/public-api/v1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-urlencode "start_date=2024-01-01 00:00:00" \
  --data-urlencode "end_date=2024-01-31 23:59:59" \
  -d "per_page=100"

# Pagination request using cursor
curl -G "https://app.cometly.com/public-api/v1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNSAxMj..."
```

```javascript JavaScript theme={null}
// Basic request without filters
const response = await fetch('https://app.cometly.com/public-api/v1/companies', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

// Request with date filtering
const params = new URLSearchParams({
  start_date: '2024-01-01 00:00:00',
  end_date: '2024-01-31 23:59:59',
  per_page: '100'
});

const filteredResponse = await fetch(`https://app.cometly.com/public-api/v1/companies?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

const filteredData = await filteredResponse.json();

// Pagination using cursor from previous response
if (filteredData.next_cursor) {
  const nextParams = new URLSearchParams({
    cursor: filteredData.next_cursor
  });

  const nextPage = await fetch(`https://app.cometly.com/public-api/v1/companies?${nextParams}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    }
  });
}
```

```php PHP theme={null}
<?php
// Basic request without filters
$baseUrl = 'https://app.cometly.com/public-api/v1/companies';
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Accept: application/json',
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

// Request with date filtering
$params = http_build_query([
    'start_date' => '2024-01-01 00:00:00',
    'end_date' => '2024-01-31 23:59:59',
    'per_page' => 100
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '?' . $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

// Pagination using cursor
if (!empty($data['next_cursor'])) {
    $nextParams = http_build_query([
        'cursor' => $data['next_cursor']
    ]);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . '?' . $nextParams);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $nextResponse = curl_exec($ch);
    curl_close($ch);
}
?>
```

```python Python theme={null}
import requests

# Basic request without filters
base_url = 'https://app.cometly.com/public-api/v1/companies'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

response = requests.get(base_url, headers=headers)
data = response.json()

# Request with date filtering
params = {
    'start_date': '2024-01-01 00:00:00',
    'end_date': '2024-01-31 23:59:59',
    'per_page': 100
}

response = requests.get(base_url, headers=headers, params=params)
data = response.json()

# Pagination using cursor from previous response
if data.get('next_cursor'):
    next_params = {
        'cursor': data['next_cursor']
    }

    next_response = requests.get(base_url, headers=headers, params=next_params)
    next_data = next_response.json()
```

## Status Codes

| Status Code | Description |
| - | - |
| 200 | Companies successfully retrieved |
| 401 | Missing or invalid API key |
| 403 | API key doesn't have permission or subscription is inactive |
| 422 | Invalid parameters provided (check error message for details) |
| 429 | Too many requests - rate limit exceeded. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) |

## Notes

* **Rate Limit**: This endpoint has a limit of **15 requests per minute** per Space. See [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md) for details.
* Results are ordered by creation date in descending order (newest first)
* Cursor pagination is used for efficient traversal of large result sets
* Date filtering is optional. When omitted, all companies are returned.
* Dates are provided in your space's configured timezone and converted to UTC for querying
* Only company `id`, `domain`, and `external_id` fields are returned in the response — `name` is not included in the list view; use [Get Company](https://docs.cometly.com/api-reference/endpoint/get-company.md) to retrieve it


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