Build and manage lists

Lists are the spreadsheet-like surface for working with resources in bulk. Use them to assemble a screening universe, track a themed set of targets, or enrich and analyze many records at once.

Create a list

curl -X POST https://api.metal.ai/v1/lists \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Industrial automation — Q3 screen" }'

The response returns the new list under data, including its id. Use that id to add and read entries.

Add entries

Entries are the resources a list contains. Add companies, deals, or people by referencing their id.

curl -X POST https://api.metal.ai/v1/lists/665f1c2a9b1e4a0012a3b4c5/entries \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entries": [{ "companyId": "665f1c2a9b1e4a0012a3b4c6" }] }'

Read entries

Fetch the entries in a list to read their current values, including any enriched columns. Entries are paginated like other collections.

curl "https://api.metal.ai/v1/lists/665f1c2a9b1e4a0012a3b4c5/entries?limit=100" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

Lists can hold many entries. Page through them with limit and lt as described in pagination.

Add or remove tags in bulk

POST /v1/lists/{id}/entries/bulk-tags adds or removes tags across selected entries. Metal applies the change to every tags column on the list. On lists with write-back enabled, Metal also writes the tags to the underlying records when the list’s record type supports tag write-back. Today that means funds, limited partners, and fundraising processes; on company, deal, and person lists, a write-back-enabled list reports error for every record-linked entry and writes no tag to the record; entries without a usable reference stay list-only. Send the entry IDs, the tag IDs, and an operation of add or remove. entryIds accepts 1 to 1,000 IDs and tagIds accepts 1 to 100 IDs. Metal removes duplicate IDs.

curl -X POST https://api.metal.ai/v1/lists/665f1c2a9b1e4a0012a3b4c5/entries/bulk-tags \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entryIds": ["665f1c2a9b1e4a0012a3b4d1", "665f1c2a9b1e4a0012a3b4d2"],
    "tagIds": ["665f1c2a9b1e4a0012a3b4e1"],
    "operation": "add"
  }'

Metal applies the change per entry, not all-or-nothing. Valid entries update even when others fail. The response reports a status for each entry. This sample comes from a fund list; affectedResources is recorded for every write-back record type:

{
  "data": {
    "updatedCount": 1,
    "noOpCount": 1,
    "notFoundCount": 0,
    "errorCount": 0,
    "results": [
      { "entryId": "665f1c2a9b1e4a0012a3b4d1", "status": "updated" },
      { "entryId": "665f1c2a9b1e4a0012a3b4d2", "status": "noOp" }
    ],
    "affectedResources": [{ "type": "fund", "id": "665f1c2a9b1e4a0012a3b4c6" }]
  }
}

updated: at least one tags column changed.
noOp: the entry already had (for add) or already lacked (for remove) every tag.
notFound: the entry ID isn’t in this list.
error: the entry could not be changed, for example because you can’t edit the underlying record or the list’s record type doesn’t support tag write-back. Metal continues with the rest of the batch.

affectedResources lists the underlying records Metal updated through write-back. It’s omitted when write-back is off or nothing changed. Metal returns 400 when a request exceeds the limits, uses an unknown tag ID or a tag of the wrong type, or targets a list with no tags column. It returns 403 when you don’t have access to the list.

Find lists

GET /v1/lists returns the lists you can access. Narrow the results with these query parameters:

filter: my-lists (lists you own), shared-with-me (lists shared directly with you), or firmwide (lists that are not private). Any other non-empty value returns 400.
q: a case-insensitive substring match on the list name. It combines with filter.

curl "https://api.metal.ai/v1/lists?filter=my-lists&q=automation&limit=50" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

The response does not include a total count. Instead, metadata.hasMore is true when another page exists. Keep requesting the next page until hasMore is false. page is capped at 100. To iterate past the first 100 pages, use the lt cursor instead. See pagination.

{
  "data": [{ "id": "665f1c2a9b1e4a0012a3b4c5", "name": "Industrial automation — Q3 screen" }],
  "metadata": { "page": 1, "limit": 50, "hasMore": false }
}

Manage the list

Action	Endpoint
List all lists	`GET /v1/lists`
Get one list	`GET /v1/lists/{id}`
Rename or update	`PUT /v1/lists/{id}`
Delete	`DELETE /v1/lists/{id}`
Read entries	`GET /v1/lists/{id}/entries`
Add entries	`POST /v1/lists/{id}/entries`
Add or remove tags in bulk	`POST /v1/lists/{id}/entries/bulk-tags`

A common workflow

Assemble the universe

Search for relevant companies and add the matches as entries.

Enrich in bulk

Enrich at the list level so every entry gets firmographics and financials. See enrich companies.

Screen and export

Read entries as JSON to rank, filter, or load results into your own system. Paginate with limit and lt. Metal does not offer a native warehouse connector or Parquet dump — see portability.

Lists pair naturally with workflows: run a workflow over a list to screen an entire set of targets in one pass.

Core tasks

API essentials

Build and manage lists

Create a list

Add entries

Read entries

Add or remove tags in bulk

Find lists

Manage the list

A common workflow

​Create a list

​Add entries

​Read entries

​Add or remove tags in bulk

​Find lists

​Manage the list

​A common workflow

Create a list

Add entries

Read entries

Add or remove tags in bulk

Find lists

Manage the list

A common workflow