Skip to main content
Use Plyne data tools when your research needs a specific company profile, job listing, post, review or other public record. Each request retrieves data and source references for you or your agent to interpret. The API, paid MCP connection and portal use the same tool contracts. Each tool reference documents its accepted fields, native source options, result shape and billing policy.

First tool request

Describe, plan and execute a company lookup.

Source chains

Explore fallback behavior and source selection.
For reservation, final charging and interrupted operations, read credits and request recovery.

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}/plan to validate, and POST /v1/tools/{id}/execute to acquire data.
  • MCP: connect your agent to /mcp with OAuth or a workspace API key. The same connection includes saved-data tools. Use plan_tool to validate a proposed request for free. Acquisition tool names match API IDs; put idempotency_key inside their arguments.
  • Portal: open a tool and select Docs for the same usage guidance, parameters and API/MCP examples.
The Search jobs reference is a complete example. The OpenAPI document includes describe, plan and execute operations for every registered tool.

Authenticate

Use your API base URL and a valid workspace key from Developer settings. Send Authorization: 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 through plan_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 an Idempotency-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 returns id, 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 in pagination.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 returns code 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.