## List all companies

**get** `/v2/companies`

Returns all companies in your organization with cursor-based pagination.

### Query Parameters

- `limit` - Number of companies to return (1-100, default: 10)
- `cursor` - Opaque cursor from a previous response for pagination

### Response Structure

The response includes:

- `object` - Always "list"
- `data` - Array of company objects
- `nextCursor` - Cursor for the next page (null if no more results)

### Company Object

Each company includes:

- `id` - Featurebase internal ID (MongoDB ObjectId)
- `companyId` - External company ID from your system
- `name` - Company name
- `monthlySpend` - Monthly spend/revenue
- `industry` - Industry
- `website` - Company website URL
- `plan` - Plan/tier name
- `linkedUsers` - Number of users linked to this company
- `companySize` - Employee headcount
- `lastActivity` - Last activity timestamp
- `customFields` - Custom field values
- `createdAt` - Creation timestamp
- `updatedAt` - Last update timestamp

### Example Response

```json
{
  "object": "list",
  "data": [
    {
      "object": "company",
      "id": "507f1f77bcf86cd799439011",
      "companyId": "comp_12345",
      "name": "Acme Inc",
      "monthlySpend": 5000,
      "industry": "Technology",
      "website": "https://acme.com",
      "plan": "enterprise",
      "linkedUsers": 15,
      "companySize": 250,
      "lastActivity": "2025-01-15T00:00:00.000Z",
      "customFields": { "location": "Europe" },
      "createdAt": "2025-01-01T12:00:00.000Z",
      "updatedAt": "2025-01-10T15:30:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}
```

### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

### Query Parameters

- `cursor: optional string`

  An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.

- `limit: optional number`

  A limit on the number of companies to be returned, between 1 and 100.

### Header Parameters

- `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"`

  - `"2026-01-01.nova"`

  - `"2025-12-12.clover"`

### Returns

- `data: array of Company`

  Array of companies

  - `id: string`

    Featurebase internal ID

  - `companyId: string`

    External company ID from your system

  - `companySize: number`

    Company employee headcount

  - `createdAt: string`

    ISO date when company was created

  - `industry: string`

    Industry

  - `lastActivity: string`

    ISO date of last activity

  - `linkedUsers: number`

    Number of users linked to this company

  - `monthlySpend: number`

    Monthly spend

  - `name: string`

    Company name

  - `object: "company"`

    Object type identifier

    - `"company"`

  - `plan: string`

    Plan or tier name

  - `updatedAt: string`

    ISO date when company was last updated

  - `website: string`

    Company website URL

  - `customFields: optional map[unknown]`

    Custom field values

- `nextCursor: string`

  Cursor for fetching the next page (cursor-based pagination)

- `object: "list"`

  Object type identifier

  - `"list"`

### Example

```http
curl https://do.featurebase.app/v2/companies \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "companyId": "comp_12345",
      "companySize": 250,
      "createdAt": "2025-01-01T12:00:00.000Z",
      "industry": "Technology",
      "lastActivity": "2025-01-15T00:00:00.000Z",
      "linkedUsers": 15,
      "monthlySpend": 5000,
      "name": "Acme Inc",
      "object": "company",
      "plan": "enterprise",
      "updatedAt": "2025-01-10T15:30:00.000Z",
      "website": "https://acme.com",
      "customFields": {
        "location": "bar",
        "priority": "bar"
      }
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
  "object": "list"
}
```