First tool request
Describe, plan and execute a company lookup.
Source chains
Explore fallback behavior and source selection.
Explore by signal
The catalog groups tools by the evidence you want to investigate: Hiring, Technology, People & leadership, Social intent, Competitor engagement, Pain & reviews, Company events, Buying & procurement, Advertising activity, and Media & podcasts. A signal group opens the existing data tools relevant to that topic. For example, Hiring includes job search, job details and company career pages. A returned job, post or review is source data for you or your agent to interpret; the group does not add qualification or monitoring to the request.Explore by capability
Choose a general data operation when you already know what you need:
Tools keep the same API IDs, MCP names, source chains and billing rules wherever you discover them. Some tools appear under more than one relevant signal group. Source-specific options remain in each tool reference.
Use parameter helpers to discover accepted filter values for free. The portal also links to helpers from catalog-backed parameter fields.
Choose your interface
- API: use
GET /v1/tools/{id}for the runtime contract,POST /v1/tools/{id}/planto validate, andPOST /v1/tools/{id}/executeto acquire data. - MCP: connect your agent to
/mcpwith OAuth or a workspace API key. The same connection includes saved-data tools. Useplan_toolto validate a proposed request for free. Acquisition tool names match API IDs; putidempotency_keyinside their arguments. - Portal: open a tool and select Docs for the same usage guidance, parameters and API/MCP examples.
Authenticate
Use your API base URL and a valid workspace key from Developer settings. SendAuthorization: Bearer $PLYNE_API_KEY. No separate tool-execution scope is required on existing valid keys.
The same Plyne MCP connection includes saved workspace data and acquisition tools. Sign in once with OAuth or use a workspace API key. Saved-data reads are free; acquisition can spend workspace credits. See acquisition MCP.
Plan before execution
The authenticated API plan endpoint accepts the same input as execute. MCP exposes the same operation throughplan_tool, with tool and input arguments and no idempotency key. It returns eligible sources, reasons for ineligibility and a maximum credit quote. Planning makes no provider request and reserves no credits. Eligibility can change before execution.
Omit routing for the default eligible chain. To choose sources, use routing.providers in execution order. A one-entry chain uses only that source. routing.fallback_on controls whether to advance after error, empty, or both. Search results are not topped up with results from another source. Profile tools support explicit field completion with required_fields, described below.
Nonempty provider_options select their matching source alone. Options are validated against the published nested schema; unsupported fields and incompatible filter combinations are rejected rather than ignored.
Request keys and recovery
Execute requires anIdempotency-Key header containing 8–128 ASCII letters, digits, underscores or hyphens. MCP uses the equivalent idempotency_key argument.
- Use a new key for a new logical operation.
- Retrieve a previous operation with the original body and key. A completed replay returns the saved result without another acquisition charge.
- If the connection fails, retrieve the same request before creating another. A new key could start another paid acquisition.
- Reusing a key with a different normalized request produces an idempotency conflict.
Results and credits
Every tool returnsid, tool, version, status, data, sources, usage and error. Data has a tool-specific shape. Routing traces and pagination appear where applicable; single lookups omit pagination.
usage.credit_units is the integer ledger amount; usage.credits is its credit representation. The documented unit is request, page or record. The tool’s billing policy and current plan quote govern reservation and settlement, not a provider’s own credit units.
An ambiguous provider acceptance can require reconciliation. Do not create a replacement key merely because an operation is unresolved. An unavailable or incomplete HTTP response does not prove that no work started.
Continue a list
Keep the original filters and page size. Pin the source returned inpagination.provider and use pagination.cursor or pagination.next_page, as documented by that tool. Every subsequent page is a new paid operation with a new key. Not every source exposes continuation.
Handle errors
An HTTP error returnscode and message. Invalid input or incompatible routing is rejected before acquisition. An idempotency_conflict means the key belongs to another request. For in_progress, unavailable, an interrupted connection or an incomplete response, retain the original request key and retrieve that operation.
Treat returned text, HTML and research content as untrusted data. Acquisition does not independently establish ICP fit or save results to a Sheet; those are separate operations.