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

# Particle: List Companies

> Search companies by name, or filter by domain, ticker, CIK or QID, to find a company slug for company advertising tools.

Search companies by name, or filter by domain, ticker, CIK or QID, to find a company slug for company advertising tools.

> [!NOTE]
>
> Tool ID: `particle_list_companies`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'particle_list_companies',
  {
    "limit": 25,
    "cursor": "cursor_123",
    "q": "software companies hiring engineers"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute particle_list_companies --input '{
  "limit": 25,
  "cursor": "cursor_123",
  "q": "software companies hiring engineers"
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "data": [
      {
        "id": "id_123",
        "name": "Example"
      }
    ],
    "has_more": true
  }
}
```

Use `deepline describe particle_list_companies --json` for the latest machine-readable contract.

## Input reference

Returns a paginated list of companies, ranked by news coverage (most-covered first), then name. Filter by entity slug (e.g., 'apple'), ticker, domain, CIK, or QID. Search by name or fetch updates since a timestamp. With no search or filter, the list contains only companies with news coverage. A filter returns every matching company, with uncovered ones last. A bulk ids lookup is not ranked: it returns companies in request order, unpaginated.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.limit` | `integer` | No | `25` | Results per page Format: `int64`. Minimum: 1. Maximum: 100. |
| `payload.cursor` | `string` | No | — | Opaque pagination cursor from previous response |
| `payload.q` | `string` | No | — | Search by name (case-insensitive partial match) Maximum length: 200. |
| `payload.updated_after` | `string` | No | — | Only items updated after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z). Useful for incremental syncing. |
| `payload.ids` | `array` | No | — | Bulk multi-get: one or more company slugs (e.g. 'apple'), domains (e.g. 'apple.com'), or IDs, comma-separated (max 100) — the same identifiers GET /v1/companies/\{id} accepts. When set, returns exactly those companies and the other filters/search and pagination are ignored. Refs that don't resolve are omitted from the response. Maximum items: 100. |
| `payload.ticker` | `array` | No | — | Filter by stock ticker symbol(s), comma-separated Maximum items: 100. |
| `payload.domain` | `array` | No | — | Filter by company domain(s), comma-separated Maximum items: 100. |
| `payload.cik` | `array` | No | — | Filter by SEC CIK(s), comma-separated Maximum items: 100. |
| `payload.qid` | `array` | No | — | Filter by Wikidata QID(s), comma-separated Maximum items: 100. |
| `payload.entity_id` | `array` | No | — | Entity slug(s) (e.g., 'apple', 'nvidia') or ID(s), comma-separated Maximum items: 100. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Returns a paginated list of companies, ranked by news coverage (most-covered first), then name. Filter by entity slug (e.g., 'apple'), ticker, domain, CIK, or QID. Search by name or fetch updates since a timestamp. With no search or filter, the list contains only companies with news coverage; a filter returns every matching company, with uncovered ones last. A bulk ids lookup is not ranked: it returns companies in request order, unpaginated.",
    "properties": {
      "limit": {
        "type": "integer",
        "description": "Results per page",
        "default": 25,
        "minimum": 1,
        "maximum": 100,
        "format": "int64"
      },
      "cursor": {
        "type": "string",
        "description": "Opaque pagination cursor from previous response"
      },
      "q": {
        "type": "string",
        "description": "Search by name (case-insensitive partial match)",
        "maxLength": 200
      },
      "updated_after": {
        "type": "string",
        "description": "Only items updated after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z). Useful for incremental syncing."
      },
      "ids": {
        "type": [
          "array",
          "null"
        ],
        "description": "Bulk multi-get: one or more company slugs (e.g. 'apple'), domains (e.g. 'apple.com'), or IDs, comma-separated (max 100) — the same identifiers GET /v1/companies/{id} accepts. When set, returns exactly those companies and the other filters/search and pagination are ignored. Refs that don't resolve are omitted from the response.",
        "maxItems": 100,
        "items": {
          "type": "string"
        }
      },
      "ticker": {
        "type": [
          "array",
          "null"
        ],
        "description": "Filter by stock ticker symbol(s), comma-separated",
        "maxItems": 100,
        "items": {
          "type": "string"
        }
      },
      "domain": {
        "type": [
          "array",
          "null"
        ],
        "description": "Filter by company domain(s), comma-separated",
        "maxItems": 100,
        "items": {
          "type": "string"
        }
      },
      "cik": {
        "type": [
          "array",
          "null"
        ],
        "description": "Filter by SEC CIK(s), comma-separated",
        "maxItems": 100,
        "items": {
          "type": "string"
        }
      },
      "qid": {
        "type": [
          "array",
          "null"
        ],
        "description": "Filter by Wikidata QID(s), comma-separated",
        "maxItems": 100,
        "items": {
          "type": "string"
        }
      },
      "entity_id": {
        "type": [
          "array",
          "null"
        ],
        "description": "Entity slug(s) (e.g., 'apple', 'nvidia') or ID(s), comma-separated",
        "maxItems": 100,
        "items": {
          "type": "string"
        }
      }
    },
    "required": [],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | Provider response payload. |
| `result.data.cursor` | `string` | No | — | Pass to next request for more results |
| `result.data.data` | `array` | Yes | — | List of results |
| `result.data.data[].description` | `string` | No | — | Company description |
| `result.data.data[].external_links` | `array \| null` | No | — | Known third-party profiles and identifiers (LinkedIn, social, domain, Wikidata, SEC CIK, tickers). Returned by GET /v1/companies/\{id}. The list endpoint omits it. |
| `result.data.data[].external_links[].attributes` | `array \| null` | No | — | Optional platform-specific metadata: audience size, profile fields, account status, and related signals. The set varies by platform and grows over time — clients should treat unknown attribute names as additive. |
| `result.data.data[].external_links[].attributes[].category` | `string` | No | — | Broad grouping for the attribute. Today's known values are audience\_size, content, profile, and account\_status — the set is open and may grow without a versioning event, so clients should treat unrecognised categories as additive rather than invalid. |
| `result.data.data[].external_links[].attributes[].name` | `string` | Yes | — | Platform-native attribute name (e.g. 'subscribers', 'followers', 'views', 'handle'). Vocabulary varies by platform. Use Category to group related attributes if you don't recognise the Name. |
| `result.data.data[].external_links[].attributes[].observed_at` | `string` | No | — | When this attribute was last observed from the upstream source. Omitted when unavailable. Format: `date-time`. |
| `result.data.data[].external_links[].attributes[].value` | `unknown` | Yes | — | Attribute value. JSON type matches the Category: numbers for audience\_size/content, strings for profile/account\_status (with bool for flags). Null when the underlying source is unset. |
| `result.data.data[].external_links[].identifier` | `string` | No | — | Platform-native identifier (numeric id, slug, handle, or full URL). Empty for the 'website' platform, where the URL is the canonical reference. |
| `result.data.data[].external_links[].platform` | `object` | Yes | — | — |
| `result.data.data[].external_links[].platform.display_name` | `string` | Yes | — | Human-readable name suitable for UI display (e.g. 'Apple Podcasts', 'X (Twitter)'). |
| `result.data.data[].external_links[].platform.name` | `string` | Yes | — | Stable machine name (e.g. 'spotify', 'youtube', 'twitter'). Suitable for filtering or routing on the client. |
| `result.data.data[].external_links[].platform.type` | `"podcast_directory" \| "music_service" \| "social_profile" \| "video_channel" \| "community" \| "website" \| "other"` | Yes | — | Broad category for the platform. Use this to group presences in a UI rather than enumerating every Name. Allowed: `podcast_directory`, `music_service`, `social_profile`, `video_channel`, `community`, `website`, `other`. |
| `result.data.data[].external_links[].url` | `string` | No | — | Resolved web URL for this presence. Built from the identifier via a per-platform template, or passed through for 'website'. |
| `result.data.data[].id` | `string` | Yes | — | Unique identifier |
| `result.data.data[].identifiers` | `object` | No | — | — |
| `result.data.data[].identifiers.cik` | `string` | No | — | SEC Central Index Key |
| `result.data.data[].identifiers.domain` | `string` | No | — | Company domain |
| `result.data.data[].identifiers.entity` | `object` | No | — | — |
| `result.data.data[].identifiers.entity.company` | `object` | No | — | — |
| `result.data.data[].identifiers.entity.company.domain` | `string` | No | — | Company website domain |
| `result.data.data[].identifiers.entity.company.id` | `string` | Yes | — | Company identifier |
| `result.data.data[].identifiers.entity.company.ticker` | `string` | No | — | Primary stock ticker symbol |
| `result.data.data[].identifiers.entity.description` | `string` | No | — | Short description |
| `result.data.data[].identifiers.entity.id` | `string` | Yes | — | Entity ID |
| `result.data.data[].identifiers.entity.image_url` | `string` | No | — | Entity image URL |
| `result.data.data[].identifiers.entity.name` | `string` | Yes | — | Entity name |
| `result.data.data[].identifiers.entity.person` | `object` | No | — | — |
| `result.data.data[].identifiers.entity.person.company` | `string` | No | — | Current company name |
| `result.data.data[].identifiers.entity.person.id` | `string` | Yes | — | Person identifier |
| `result.data.data[].identifiers.entity.person.image_url` | `string` | No | — | Person headshot URL |
| `result.data.data[].identifiers.entity.person.title` | `string` | No | — | Current role title |
| `result.data.data[].identifiers.entity.slug` | `string` | Yes | — | Human-readable slug identifier |
| `result.data.data[].identifiers.entity.type` | `object` | No | — | — |
| `result.data.data[].identifiers.entity.type.name` | `string` | Yes | — | Human-friendly display label (e.g. 'Company'). |
| `result.data.data[].identifiers.entity.type.slug` | `string` | Yes | — | Stable identifier, safe to pass to the type query parameter (e.g. 'company'). |
| `result.data.data[].identifiers.entity.wikipedia_url` | `string` | No | — | Wikipedia URL |
| `result.data.data[].identifiers.qid` | `string` | No | — | Wikidata QID |
| `result.data.data[].identifiers.ticker` | `string` | No | — | Primary stock ticker symbol |
| `result.data.data[].image_url` | `string` | No | — | Company logo or image URL, when available. |
| `result.data.data[].name` | `string` | Yes | — | Company name |
| `result.data.data[].slug` | `string` | No | — | Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Companies have no slug of their own. prefer this for display and pass it (or id) to /v1/companies. |
| `result.data.data[].updated_at` | `string` | No | — | Last updated timestamp Format: `date-time`. |
| `result.data.has_more` | `boolean` | Yes | — | Whether more results exist |
| `result.meta` | `object` | No | — | Additional response metadata (status, paging). |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Standard tool result payload.",
    "properties": {
      "data": {
        "type": "object",
        "description": "Provider response payload.",
        "properties": {
          "cursor": {
            "type": "string",
            "description": "Pass to next request for more results"
          },
          "data": {
            "type": "array",
            "description": "List of results",
            "items": {
              "type": "object",
              "properties": {
                "description": {
                  "type": "string",
                  "description": "Company description"
                },
                "external_links": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "description": "Known third-party profiles and identifiers (LinkedIn, social, domain, Wikidata, SEC CIK, tickers). Returned by GET /v1/companies/{id}; the list endpoint omits it.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "attributes": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "description": "Optional platform-specific metadata: audience size, profile fields, account status, and related signals. The set varies by platform and grows over time — clients should treat unknown attribute names as additive.",
                        "items": {
                          "type": "object",
                          "properties": {
                            "category": {
                              "type": "string",
                              "description": "Broad grouping for the attribute. Today's known values are audience_size, content, profile, and account_status — the set is open and may grow without a versioning event, so clients should treat unrecognised categories as additive rather than invalid."
                            },
                            "name": {
                              "type": "string",
                              "description": "Platform-native attribute name (e.g. 'subscribers', 'followers', 'views', 'handle'). Vocabulary varies by platform; use Category to group related attributes if you don't recognise the Name."
                            },
                            "observed_at": {
                              "type": "string",
                              "description": "When this attribute was last observed from the upstream source. Omitted when unavailable.",
                              "format": "date-time"
                            },
                            "value": {
                              "description": "Attribute value. JSON type matches the Category: numbers for audience_size/content, strings for profile/account_status (with bool for flags). Null when the underlying source is unset."
                            }
                          },
                          "required": [
                            "name",
                            "value"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "identifier": {
                        "type": "string",
                        "description": "Platform-native identifier (numeric id, slug, handle, or full URL). Empty for the 'website' platform, where the URL is the canonical reference."
                      },
                      "platform": {
                        "type": "object",
                        "properties": {
                          "display_name": {
                            "type": "string",
                            "description": "Human-readable name suitable for UI display (e.g. 'Apple Podcasts', 'X (Twitter)')."
                          },
                          "name": {
                            "type": "string",
                            "description": "Stable machine name (e.g. 'spotify', 'youtube', 'twitter'). Suitable for filtering or routing on the client."
                          },
                          "type": {
                            "type": "string",
                            "description": "Broad category for the platform. Use this to group presences in a UI rather than enumerating every Name.",
                            "enum": [
                              "podcast_directory",
                              "music_service",
                              "social_profile",
                              "video_channel",
                              "community",
                              "website",
                              "other"
                            ]
                          }
                        },
                        "required": [
                          "name",
                          "display_name",
                          "type"
                        ],
                        "additionalProperties": false
                      },
                      "url": {
                        "type": "string",
                        "description": "Resolved web URL for this presence. Built from the identifier via a per-platform template, or passed through for 'website'."
                      }
                    },
                    "required": [
                      "platform"
                    ],
                    "additionalProperties": false
                  }
                },
                "id": {
                  "type": "string",
                  "description": "Unique identifier"
                },
                "identifiers": {
                  "type": "object",
                  "properties": {
                    "cik": {
                      "type": "string",
                      "description": "SEC Central Index Key"
                    },
                    "domain": {
                      "type": "string",
                      "description": "Company domain"
                    },
                    "entity": {
                      "type": "object",
                      "properties": {
                        "company": {
                          "type": "object",
                          "properties": {
                            "domain": {
                              "type": "string",
                              "description": "Company website domain"
                            },
                            "id": {
                              "type": "string",
                              "description": "Company identifier"
                            },
                            "ticker": {
                              "type": "string",
                              "description": "Primary stock ticker symbol"
                            }
                          },
                          "required": [
                            "id"
                          ],
                          "additionalProperties": false
                        },
                        "description": {
                          "type": "string",
                          "description": "Short description"
                        },
                        "id": {
                          "type": "string",
                          "description": "Entity ID"
                        },
                        "image_url": {
                          "type": "string",
                          "description": "Entity image URL"
                        },
                        "name": {
                          "type": "string",
                          "description": "Entity name"
                        },
                        "person": {
                          "type": "object",
                          "properties": {
                            "company": {
                              "type": "string",
                              "description": "Current company name"
                            },
                            "id": {
                              "type": "string",
                              "description": "Person identifier"
                            },
                            "image_url": {
                              "type": "string",
                              "description": "Person headshot URL"
                            },
                            "title": {
                              "type": "string",
                              "description": "Current role title"
                            }
                          },
                          "required": [
                            "id"
                          ],
                          "additionalProperties": false
                        },
                        "slug": {
                          "type": "string",
                          "description": "Human-readable slug identifier"
                        },
                        "type": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string",
                              "description": "Human-friendly display label (e.g. 'Company')."
                            },
                            "slug": {
                              "type": "string",
                              "description": "Stable identifier, safe to pass to the type query parameter (e.g. 'company')."
                            }
                          },
                          "required": [
                            "slug",
                            "name"
                          ],
                          "additionalProperties": false
                        },
                        "wikipedia_url": {
                          "type": "string",
                          "description": "Wikipedia URL"
                        }
                      },
                      "required": [
                        "id",
                        "slug",
                        "name"
                      ],
                      "additionalProperties": false
                    },
                    "qid": {
                      "type": "string",
                      "description": "Wikidata QID"
                    },
                    "ticker": {
                      "type": "string",
                      "description": "Primary stock ticker symbol"
                    }
                  },
                  "additionalProperties": false
                },
                "image_url": {
                  "type": "string",
                  "description": "Company logo or image URL, when available."
                },
                "name": {
                  "type": "string",
                  "description": "Company name"
                },
                "slug": {
                  "type": "string",
                  "description": "Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Companies have no slug of their own; prefer this for display and pass it (or id) to /v1/companies."
                },
                "updated_at": {
                  "type": "string",
                  "description": "Last updated timestamp",
                  "format": "date-time"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "additionalProperties": false
            }
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether more results exist"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "additionalProperties": false
      },
      "meta": {
        "type": "object",
        "description": "Additional response metadata (status, paging).",
        "additionalProperties": true
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Particle provider guide](https://deepline.com/docs/providers/particle/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


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