> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose and run a source chain

> Control source order for a Plyne data tool, choose fallback conditions, understand source eligibility, and follow a chain through its possible results.

A Plyne source chain runs sources one at a time in the order you choose. Execution stops when a source returns usable data or a pending operation. You control whether an error or an empty result allows the next source to run.

## Default, one source or a chain

Omit `routing` to use the tool's default eligible sources. Describe the tool and call its free `/plan` endpoint to inspect the available choices for your request. Default execution can also use a capability's existing cache or identity-resolution behavior; it is not a promise that every listed source will run.

For an explicit chain, put the source IDs in `routing.providers`. One entry runs only that source. This company profile example selects Fetchin followed by Harvest:

```json theme={null}
{
  "linkedin_url": "https://www.linkedin.com/company/plyne-ai",
  "routing": {
    "providers": ["fetchin", "harvest"],
    "fallback_on": ["error", "empty"]
  }
}
```

Submit the body to `/v1/tools/company_profile/plan` before `/execute`. Both sources must be configured and support the request. The example illustrates chain selection, not a guarantee that either source will return a profile.

## How a chain runs

Plyne checks the request before acquisition. With a valid explicit chain, it calls the first source and evaluates its result. An enabled fallback condition advances to the next source, if one remains. By default, a later usable result does not include or merge the earlier source's results. Profile field completion is an explicit exception described below.

Example outcome

Back
Next

> [!NOTE]
>
> The walkthrough uses simulated outcomes and generic source labels. It sends no request and spends no credits. It illustrates the shared chain behavior, not an account's live source availability.

| Source outcome | Chain behavior |
| - | - |
| Usable data, including usable partial data | Return that source's result and stop. |
| Pending operation | Return pending and stop; retrieve the same request to check progress. |
| Error, or partial result without usable data | Try the next source only if `error` is enabled. |
| Empty result | Try the next source only if `empty` is enabled. |
| Invalid request or incompatible explicit chain | Reject before acquisition. |

If all attempted sources are empty, the operation can return `not_found`. If a chain cannot produce usable data after a failed attempt, it can return `failed`. Inspect the tool's status, error and routing trace instead of treating every HTTP 200 as successful acquisition.

## Choose fallback conditions

`fallback_on` accepts `error`, `empty`, or both. If you omit it from a multi-source chain, both conditions are enabled. An empty array does not disable fallback; use a one-entry chain to select only one source.

A chain does not query every source for comparison or fill a short page from another source. Use separate operations with new keys if you intentionally want independent results from multiple sources.

## Keep filter meanings intact

Every selected source must preserve your requested filters. For example, title-only matching and a keyword search across title and description are different operations. Plyne rejects an incompatible explicit chain rather than silently dropping a filter.

Nonempty `provider_options` select their matching source alone. Read the tool's published schema for the accepted namespace and fields. Source IDs and option namespaces can be platform names such as `x`, `reddit` or `crunchbase`; these identify the public data source, not its underlying transport.

## Read the routing trace

The response's `routing` metadata reports the mode, attempted sources and their outcomes, and the selected source where applicable. A selected source is not by itself proof of usable data: inspect `status` and `data` as well.

For paginated tools, continue with the source and continuation fields returned by that tool. Keep the filters and page size unchanged. Do not switch sources in the middle of a result set. See [tool execution](https://docs.plyne.ai/tools/overview.md) and [credits and recovery](https://docs.plyne.ai/guides/credits-and-recovery.md).

## Complete profile fields

For `company_profile` and `person_profile`, set `required_fields` to the top-level output fields you need. Omission preserves the existing resolver and fallback behavior. With this option, the default eligible source chain—or your explicit `routing.providers` chain—continues after a usable but incomplete profile. Execution stops as soon as every requested field is present. Errors and empty results follow routing.fallback\_on; a pending operation pauses the chain.

```json theme={null}
{
  "linkedin_url": "https://www.linkedin.com/company/example",
  "required_fields": ["description", "country_code"],
  "routing": {
    "providers": ["fetchin", "harvest"],
    "fallback_on": ["error", "empty"]
  }
}
```

Sources must identify the same entity through shared LinkedIn or domain anchors. Conflicting identities are rejected. The first populated value is retained; subsequent sources fill missing fields. Employment objects and headcount bundles are not assembled from incompatible pieces.

The response includes `fulfillment.satisfied`, `fulfillment.missing_fields` and `fulfillment.field_sources`. Exhausting the chain with usable but incomplete data returns `partial`. An empty array or unknown field is not a supported requirement in the public schema. This is field availability, not an accuracy guarantee.

The request retains the tool's quoted request price; source attempts do not create separate customer requests. Inspect `usage` for the final charge. API and MCP use the same contract.

## Find and validate work email

`work_email` finds an address through FullEnrich and applies the shared email validation policy. A native valid status avoids an extra validation call; other statuses are checked with ZeroBounce. This is a find-and-validate pipeline, not a chain of interchangeable finding sources.

Set `verification: "verified"` to accept only a valid address. Set `verification: "allow_catch_all"` to also accept catch-all addresses, which remain unverified. Omitting the option preserves catch-all acceptance. No acceptable address returns `not_found`; a validation failure returns an error rather than an unchecked address.

Returned addresses include `verification.status`, `verification.provider` and `verification.checked_at`. An explicit requirement also returns `fulfillment`. Poll or replay the same request to retrieve the result without starting another finding job.

## Additional fields

Company and person profiles, job search, job details and supported social tools
automatically return reviewed additional fields without extra provider calls. The common record keeps its normal shape;
documented source business fields appear in `data.additional_fields`, grouped by
source.

Only values already preserved in the common record are removed as duplicates.
For example, if the common `id` is `123` and a source also returns
`shareUrn: "urn:li:share:456"`, the different URN remains in
`additional_fields`. Structured source fields can remain intact when their
shape differs from the common schema.

Unknown fields, provider billing and transport envelopes are excluded. This
option does not run extra provider calls or turn profile enrichment into an
email or phone lookup. Use each tool's published output schema to see its
supported fields.

### Response size

Responses support up to 4 MiB. If additional fields make a response exceed this
limit, they are omitted and `warnings` includes `additional_fields_omitted`.
Common records, source evidence and pagination remain available, with the usual
billing policy. If the common response alone is too large, the request fails with
`result_too_large` and is not charged. Replaying the same key returns the saved
response without another source call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.