Running AI Research through your own AI (URL and MCP endpoint)

"Your AI" in AI Research is a small, self-documenting API rather than a chat prompt: your AI tool fetches one URL, reads what it's told to do, and reports matches back by calling a handful of actions. This article covers the technical shape of it; for the product-level setup, see "Letting your own AI research for you."

The URL and the MCP endpoint#

Generating a research gives you two equivalent doors onto the same run: a plain URL for your AI, which any AI tool that can fetch a URL and make JSON requests can use directly, and an MCP URL, the same research exposed as an MCP server for Claude Desktop, ChatGPT connectors and other MCP-capable agents. Both are read with a GET request first — it returns a self-describing brief (your mission, a deadline, the rules to follow, a worked example and the exact actions available) — then driven with POST requests (or MCP tool calls) from there. Neither needs a user session; the secret is the token in the URL itself.

What your AI can do#

Every research token can call log a progress update (the only way you see what it's doing live), add_hit to report a match, complete when the mission is done, and fail if it can't proceed. find_linkedin and web_search come with the Find LinkedIn and Web search switches (both free and on by default), plus whichever other sources you switched on when generating the link — the same per-source switches as a ListPlus-run research — and, only in Your AI mode, verify_email and enrich_hit. A hit needs a stable id (its email or LinkedIn URL, never invented); re-posting the same id with more fields enriches that hit instead of duplicating it.

enrich_hit needs a target list#

enrich_hit completes an already-reported hit with real provider data — email, phone, LinkedIn, job title, company — but only once that hit has reached a target list (see "Getting AI Research hits into a list automatically"); called before a target list is set, it's rejected and nothing is charged.

The credit cap is enforced on every call#

Every paid call — database, LinkedIn posts, Reddit, X, BuiltWith, verify_email or enrich_hit — is checked against two things before it runs: the research's own spending cap (10, 25 or 50 credits, set when the link was generated) and the workspace owner's actual balance. A call that would push spend over either one is rejected and charged nothing — reserved credits are rolled back on any failure — so a leaked link can never spend more than the cap allows, and a workspace that runs out of balance simply stops it from spending further.

How long it lives#

The link accepts new results for about 24 hours after you generate it; after that, writes are rejected and your AI needs a fresh link. The research itself — and everything already reported — is kept for the number of days you chose when generating it (1, 3 or 7), unless you also turned on automatic hand-off to a list, in which case the research becomes standing and doesn't expire at all.

For advanced users#

The GET response includes both deadlines explicitly (writeWindowEndsAt for the 24-hour link, campaignEndsAt for the keep-time) so an agent can pace itself without guessing. Every action call is untrusted input from the agent's point of view in reverse too: ListPlus treats page content the agent fetches as data, never instructions, and the briefing tells the agent the same about what it reads on the web. The toolset is generated per run from the same switch permissions a ListPlus-run research uses, so a link minted with only the database and news switches on exposes only those tools in its schema — nothing to discover or guess.

Related topics: your-ai-researches · research-results-to-a-list · research-costs-and-sources · api-connection-overview · api-costs-and-security.

FAQ#

What do I get when I generate a research link for my own AI?#

Two equivalent doors onto the same research: a plain URL any AI tool can fetch and POST JSON to, and an MCP URL for Claude Desktop, ChatGPT connectors and other MCP-capable agents. Both start with a GET request that returns a self-describing brief — your mission, the rules, a worked example and the exact actions available.

Does my AI need to sign in to use the research link?#

No — the link's own secret token is the only authentication; there's no user session or separate API key involved. Anyone holding the link can use it for that one research, so treat it like a password.

What actions can my AI call?#

Always available: log (progress updates), add_hit (report a match), complete and fail. find_linkedin and web_search come with the Find LinkedIn and Web search switches (both free and on by default), plus whichever other sources you switched on when generating the link. Verify_email and enrich_hit are Your-AI-only and both cost credits.

How does re-reporting the same hit work?#

Every hit needs a stable id — its email or LinkedIn URL, never invented — and posting add_hit again with the same id merges new fields into that hit instead of creating a duplicate. This is also how enrich_hit and later corrections work.

Why did my AI's enrich_hit call get rejected?#

enrich_hit only works on a hit that has already reached a target list, so turn on automatic hand-off to a list before your AI tries to enrich anything. A rejected call charges nothing.

How is the credit cap actually enforced on the API?#

Every paid call — database, LinkedIn posts, Reddit, X, BuiltWith, verify_email or enrich_hit — is checked against both the research's own spending cap and the workspace owner's real balance before it runs; either being insufficient rejects the call and charges nothing, with any reserved credits rolled back. This makes it safe to hand a capped link to an AI you don't fully control.

How long does my AI have to call the research link?#

About 24 hours from when you generated it — the GET response states the exact deadline, and writes are rejected after it passes. Generate a fresh link if your AI needs more time.

Does the research link expire, separately from the 24-hour window?#

Yes — you also pick how long the whole research (and its matches) is kept, 1, 3 or 7 days, which is longer-lived than the 24-hour write window and only affects when it's deleted, not when writes stop. Turning on automatic hand-off to a list removes that expiry entirely.

Can I see which tools a given research link exposes?#

Yes — a GET request to the link returns the exact toolset for that run, built from the sources you switched on when generating it; a link minted with fewer sources on genuinely doesn't list the others; there's nothing extra for an agent to discover.