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

<ParamField query="per_page" type="integer" default="200">
  Number of companies to return per page. Minimum: 1, Maximum: 5000
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response. Use this to fetch the next page of results.
</ParamField>

<ParamField query="start_date" type="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`
</ParamField>

<ParamField query="end_date" type="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`
</ParamField>

## Response

### Success Response

The response follows Laravel's cursor pagination structure:

<ResponseField name="data" type="array">
  Array of company objects. Each company includes:

  * `id` (integer): The unique identifier of the company
  * `domain` (string): The domain associated with this company
</ResponseField>

<ResponseField name="path" type="string">
  The base URL path for the endpoint
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Cursor for the next page of results. `null` if there are no more pages.
</ResponseField>

<ResponseField name="next_page_url" type="string | null">
  Full URL for the next page of results. `null` if there are no more pages.
</ResponseField>

<ResponseField name="prev_cursor" type="string | null">
  Cursor for the previous page of results. `null` if on the first page.
</ResponseField>

<ResponseField name="prev_page_url" type="string | null">
  Full URL for the previous page of results. `null` if on the first page.
</ResponseField>

### Error Response

<ResponseField name="message" type="string">
  Error description explaining what went wrong
</ResponseField>

## Example Requests

<CodeGroup>
  ```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" \
    -d "start_date=2024-01-01 00:00:00" \
    -d "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()
  ```
</CodeGroup>

## 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](/introduction/rate-limiting) |

## Notes

* **Rate Limit**: This endpoint has a limit of **15 requests per minute** per Space. See [Rate Limiting](/introduction/rate-limiting) 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` and `domain` fields are returned in the response