# Share lists with your AI agent

Source: https://listplus.ai/en/help/ai-agents-api/agent-list-access
Last updated: 2026-11-07

A connected AI — Claude, ChatGPT, Claude Code, Cursor, n8n or your own
code — works on the lists you **share** with it, and on no others. Each
shared list has its own rights: read and check, edit, or everything
including enrichment and pipelines. You connect the AI once (see "[Agent
keys — let any AI agent find, check and enrich records](https://listplus.ai/en/help/ai-agents-api/agent-keys)"), then share lists
with it.

Records are never deleted through an agent. Hiding records is the most it
can do to them. A hidden record leaves the normal flow — the working list,
the checks, rules, enrichment and the sync skip it — and can be shown again
at any time.

## Share a list

Two places, the same setting:

- **Your AI** in the left bar → the connection's **Manage** → **Lists**:
  every list of the workspace with a checkbox (the shared ones on top).
  Right after connecting, **Choose lists** in the connect dialog opens it.
- In the list: **Set up** → **Agents** (or **Agents** in the list's panel
  menu): every connection of the workspace with a checkbox.

Tick a list (or a connection) and pick what it may do:

| Preset              | What the agent may do                                                                 |
| ------------------- | ------------------------------------------------------------------------------------- |
| **Read + check**    | Read records and run the checks; nothing is written. The default.                      |
| **Edit**            | Also add records, change cells, set statuses and tags, hide records, apply fixes.      |
| **Full**            | Also fill missing fields (credits), AI columns and hand records to pipelines.          |

**Save** applies it at once — the agent's next call sees the change.
Untick to stop sharing. Only the workspace **owner or an admin** can
change this; members see which agents work on a list.

The connection's row on **Your AI** says how many lists it may work on, or
"No lists shared"; the list's setup overview shows the number of agents on
the **Agents** card. The page where Claude or ChatGPT is allowed for your
workspace says it too: the AI works only on the lists you share.

Lists the agent made itself — the lists of its searches and the ones it
created — are shared with it as **Full** by themselves and
marked **Made by this agent**. You can narrow them like any other list.

### Details

**Details** under a shared list narrows it further:

- **Columns it never sees** — the agent cannot read or filter by them.
- **Columns it may write** — "Every visible column" by default.
- **Only fill empty cells** — the agent never overwrites a value.
- **Only these sublists** — the agent sees only the records of these
  sublists ("Every record" by default).
- **Rows per query** — 100 by default, at most 1,000.

## What the agent can do on a shared list

The agent learns all of this by itself (it calls "describe the list"
first). In plain words:

- **Describe the list** — its columns, allowed values, statuses, sublists,
  the pipelines it may use and what it may do there.
- **Read records** — rows, a count, or only the record ids, filtered by
  column values or conditions.
- **Run the checks** — the 100+ data-quality checks of the app, with a
  score, the affected records and a proposed fix per check.
- **Add records** — up to 1,000 per call. A record the list already has
  (same e-mail, LinkedIn profile, or name + company) is filled in, not
  added twice; rejected records come back with the reason.
- **Change cells** — per record, or one change for many records.
- **Mark records** — set a status (which may start the list's rules, as in
  the app), add or remove tags, hide or show records.
- **Apply fixes** — a check's proposed fixes, cleaned values (spaces,
  casing, placeholders), or merged duplicates (merged rows are hidden).
- **Copy or move records** between lists it may edit (contacts to
  contacts, companies to companies). Moving hides them in the source.
- **Fill missing fields** (Full) — work e-mail, mobile, job title,
  LinkedIn, company data: the same enrichment as in the app.
- **AI column** (Full) — fill a column from others by an instruction,
  for example the gender from the first name.
- **Hand records to a pipeline** (Full) — HubSpot, Slack, lemlist … The
  pipeline's data check and release apply: a manual pipeline waits for a
  person.

Every record in an answer carries a link that opens it in ListPlus.

## Set up: the agent builds lists, columns and rules

With the connection's **Set up** right (off by default — see "Agent keys")
the agent can also build what you build in the app. What it may do on a
list follows the list's preset, as if you did it by hand:

| What                                                        | Needs                     |
| ----------------------------------------------------------- | ------------------------- |
| Create a list (it is the agent's own, shared in Full)        | Set up                    |
| Add columns: plain, choice, formula, score, assign (label), value from another list, in a list, in HubSpot, job change | Set up + **Edit** |
| AI columns: an AI criterion in a score, an AI text column    | Set up + **Full** + a day budget |
| Rules (triggers): set a status, add a tag, hide              | Set up + **Edit**         |
| Rules that hand records to a pipeline                        | Set up + **Full** (or that pipeline's share) |
| Rules that enrich (fill missing fields)                      | Set up + **Full** + a day budget |
| Change, pause or remove its own rules                        | Set up + the rights of their actions |
| Change or remove a rule someone else set up, remove a column | Set up + **Full**         |

A rule the agent set up shows **Set up by …** on its card in the list's
**Triggers** panel. It acts by itself at once, like any rule — unless the
agent set it up paused. When you save the rule yourself, it is yours: the
mark goes. A status the agent names that the list does not have yet is
created. Removing a column takes it out of the list; the records stay.

The agent hands records only to pipelines that already exist — a pipeline
can serve many lists, so you set it up once yourself in ListPlus.

## What it costs

- Reading, checking, adding, changing, marking, fixing and copying cost
  **no credits**.
- Filling missing fields is charged **per hit**, at the prices of "[Price
  list: what every action costs](https://listplus.ai/en/help/plans-credits-billing/price-list)".
- An AI column is charged by the AI's real use (usually cents), at most 10
  credits per call.
- Setting up (lists, columns, rules) costs **no credits** — except an AI
  column the agent adds: it is charged per AI answer like one you add
  yourself. Its first run over the list counts at most on the connection's
  day budget (for example 200 records × 0.02 = 4 credits); later records
  run under the list's own daily limit for AI columns.
- A rule the agent set up that **enriches** is charged per hit, at most
  its budget per record, and counts on **that connection's day budget**.
  When the day is used up, its records wait — the rule says so on its
  card and goes on by itself after midnight (UTC), or once you raise the
  budget. It never overspends. Save the rule yourself and it is yours: from
  then on it counts like your own rules.
- Handing records to a pipeline costs nothing; a pipeline that sends by
  itself charges its price per record when it delivers.
- Everything paid comes from the workspace owner's credits and stays within
  the connection's **day budget**.

A connection may make up to 120 reading calls a minute (5,000 a day) and 60
writing calls a minute (2,000 a day).

## When the agent is refused

The agent gets a clear reason it can pass on to you:

- **The list is not shared** with it, or not with the right it needs
  ("shared without editing") — share it, or pick a wider preset.
- **The list is a reference list** refreshed from its source (HubSpot,
  Google Sheets …) — change those records at the source.
- **The workspace holds more records than its plan** edits — its lists are
  read-only until the plan is upgraded.
- **The list was deleted** — its sharing goes with it.

**Related topics:** agent-keys · research-with-your-own-ai · zapier-make-n8n · segments-and-tags · pipelines-overview · roles-and-permissions · price-list.

## FAQ

### Can I give Claude or ChatGPT access to just one list?

Yes. Connect it once on **Your AI**, then share only that list (Manage →
Lists, or in the list: Set up → Agents). It sees no other list. Searches it
runs make new lists of their own, which are shared with it by themselves.

### Can the agent delete records or a list?

No. The most it can do is hide records (with Edit or Full), and hidden
records can be shown again in the list. Merged duplicates are hidden too.

### Can n8n, Make or my own code write into a list automatically?

Yes. Create a key on **Your AI** (the **n8n / Make / Code** tile), share
the list with **Edit**, and call `POST https://listplus.ai/a/v1/add_records`
with the header `Authorization: Bearer lpk_…` and `{ "list_id": "…",
"records": [ … ] }`. The same works as an MCP server. For records that
simply come in from a form or tool, a list webhook is the simpler way
(see "Zapier, Make and n8n").

### Can an agent check a customer's CSV and add only the good records?

Yes. It checks the rows first ("check records" — nothing is stored), drops
or fixes what fails, then adds the rest to a list shared with Edit, up to
1,000 per call. Duplicates of records the list already has are filled in,
not doubled. Or it adds everything to a staging list, runs the checks and
fixes there, and moves the good records into the main list.

### Why can't I delete a sublist?

An agent is limited to it (Details → Only these sublists). The message
names the agent: remove the sublist from that connection's details first.

### What happened to the per-list API connection?

It is replaced by sharing lists with a connection: one key or sign-in for
the whole workspace, with rights per list. The old `/d/…` addresses and
list tokens no longer work.

### Does sharing a list cost anything?

No. Only what the agent does that costs credits in the app too — filling
fields, AI columns, automatic pipeline deliveries — is charged, within the
connection's day budget.