Sets (preview)

Sets replace the removed /v1/agent endpoint for building people lists. A Set runs in the background: it compiles your query into a search plan, finds candidates, and checks every criterion before admitting a person. Use POST /v1/person for research on one identified person, and POST /v1/search for a quick synchronous list of up to 150 people.

Create a Set

curl https://api.ploid.com/v1/sets \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "query": "Heads of RevOps at Series B SaaS companies in New York",
      "count": 25
    }
  }'

search.count defaults to 25; self-serve Sets accept up to 500. search.criteria is optional; when omitted, criteria are derived from query. The response is 201 with the Set id, the search, an estimate under pricing, and events_url and items_url for following progress.

Budget

budget is optional and caps the credits the Set's searches may spend:

{
    "search": { "query": "Heads of RevOps at Series B SaaS companies in New York", "count": 100 },
    "budget": { "credits": 5 }
}

A search admits no more people than the remaining budget pays for. With "credits": 5 and a count of 100, the search stops after 50 admitted people, which are billed, and reports stop_reason: "budget". The API key's daily and monthly budgets still apply to the full requested count at creation. budget.llm_tokens is accepted for compatibility and currently has no effect.

Search status

GET /v1/sets/{id} returns the Set's searches, newest first, under searches. Each has id, query, count, status, criteria, behavior, created_at, finished_at, and stop_reason. stop_reason is "budget" when the search stopped because the Set budget ran out, otherwise null.

Enrichment columns are not yet available through the API: a request from an API key with a non-empty enrichments array returns 422 enrichments_unavailable. Create the Set without enrichments, then enrich admitted people with the enrichment APIs.

Endpoints

API keys can call these routes:

API keys see only admitted people in items, export, and events, and item_count counts only admitted people; status=review and status=all return admitted people for API keys. People with at least one unclear criterion (review) are never billed and are shown only in the Ploid workspace for now.

In the CSV export, a cell that a spreadsheet would run as a formula (starting with =, +, - or @, other than a phone number or plain number) is prefixed with an apostrophe so it opens as text. ?format=json returns the raw values.

Imports, enrichment columns, monitors, and additional searches into an existing Set are available in the Ploid workspace only for now.

Pricing

Searches are charged on admitted people: 1 ACU (one credit) per 10 admitted, rounded up. The charge is made when the search finishes, including for people admitted before a failure or cancellation. Nothing is charged up front. Creating a Set checks that the workspace balance covers the requested count plus the unbilled work in queued and running searches, including finished searches whose billing has not settled. Concurrent creation requests share this admission check, so they cannot each use the same remaining balance. A request without enough available credits returns 402.

Creation also reserves the estimated charge for the requested count against the API key's daily and monthly budgets. When the search finishes, that reservation is settled with its actual charge. A billing retry reuses any committed charge, and the Set's spent credits are recovered before resuming a finished search so its remaining budget reflects earlier charges.