Datasets (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.

Filters

search.filters takes the same schema as Search hard filters: title, seniority, company, industry, and location as one value or { any_of, none_of }, plus company.employee_count, company.funding_stage, company_size, experience.past_companies, and education.schools. Single values steer retrieval. Alternatives, exclusions, and the filters the index cannot hold become required criteria: each row must prove them with evidence to be admitted. They are added to your criteria or the derived ones, never replace them, and count toward the 5-criteria limit; above it the request returns 422 too_many_criteria.

{
    "search": {
        "query": "fintech founders",
        "count": 50,
        "filters": {
            "title": { "any_of": ["Founder", "CEO"] },
            "location": "New York",
            "experience": { "past_companies": { "any_of": ["Stripe", "Ramp"] } }
        }
    }
}

Freshness

search.freshness works like Search freshness: max_age_days caps how old the cached evidence behind each admitted row may be, and 0 always re-reads live sources. Sets always verify, so no search type is required.

{
    "search": {
        "query": "Heads of RevOps at Series B SaaS companies in New York",
        "count": 25,
        "freshness": { "max_age_days": 2 }
    }
}

When omitted, each search derives a window from its time-sensitive criteria — current-role wording tightens it toward ~4.6 days, location wording toward ~9 days — applied to the top count candidates, with a relaxed 7-day cache for the rest. Tighter windows cost more live reads per admitted row.

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.