How to pin Perplexity Agent API effort for repeated evaluations

This procedure is for developers or researchers preparing repeated Agent API evaluations. Before running, prepare the exact request set, select an effort level, and decide whether automatic updates are acceptable. The preparation output should be a saved configuration record against which the next run’s conditions can be checked.

The documentation lists fast, low, medium, high, and xhigh. These are configuration bundles combining a model, search, reasoning steps, system instructions, and available tools. The separate reasoning.effort parameter concerns the selected model’s reasoning. Recording reasoning.effort alone therefore does not describe the entire agent configuration. Evidence: [Perplexity — Effort](https://docs.perplexity.ai/docs/agent-api/effort).

Section sources:[1] Perplexity

A dynamic call, such as effort="low", follows the level’s active configuration. Perplexity describes updates as targeting quality improvements while staying within similar cost and latency bands. That is the stated update objective, not an independently established result here or a guarantee of identical per-request cost.

A pinned version retains a selected released configuration after the active version changes. An explicit frozen configuration moves published settings into the request itself. Our editorial selection rule is to use dynamic effort when evaluating the service’s current offering, a version for a pinned starting measurement series, and explicit fields when inspecting or changing particular settings.

• Dynamic effort: updates are accepted automatically.
• Versioned effort: moving to another released configuration becomes an explicit decision.
• Explicit configuration: model, tools, instructions, and parameters are preserved in the request.

Section sources:[1] Perplexity

Make an initial request with your chosen effort and save the response’s effort field. Send that value in subsequent requests in the series. The documentation’s fast@2026-10-16.0 illustrates the format; it does not establish that this particular version is active on your check date.

Both fast and fast@latest designate the active version. Adding @latest does not pin a configuration. Verify the transition by comparing the submitted value with the version reported in the response, preserving every explicit override alongside it.

The documentation warns that streams resumed through starting_after omit the effort field. Preserve version information from the initial response. Do not reconstruct a missing value from the model name or writing style.

Section sources:[1] Perplexity

For a frozen setup, open Current effort level values and take the complete block for the selected level. Transfer the model, tools, system instructions, and parameters; remove effort. Compare the tabs: the source explicitly warns that cURL can expose parameters not yet represented in the SDK. Copying only the model name is insufficient.

There is an important completeness boundary. For medium and high, the source describes disabled grep and medium-effort fetch_url content extraction as effort-level settings unavailable through request fields. Do not invent parameters for them. If the evaluation needs the released effort configuration itself, a pinned version is the more direct choice; equivalence of an explicit request on those settings remains unverified.

Prepare dated instructions separately. The {{current_date}} placeholder is substituted only in effort default instructions. In request-provided instructions it remains literal text. Frozen examples compute the UTC date before submission; preserve the actual submitted instruction string in the evaluation record.

Section sources:[1] Perplexity

An unknown level name, unknown version, or malformed value produces HTTP 400. First check the saved value and request format. For a pinned series, do not silently replace a failing version with latest: that changes the chosen update policy.

Overriding tools needs a different check. Alongside effort, tools merge individually rather than replacing the entire set. Configuring web_search alone leaves the level’s other tools enabled. A short tools array therefore does not establish that the agent has access only to that tool.

If you intended a fully explicit configuration, check that effort is absent and the submitted fields are complete. If effort remains, describe the request as an effort configuration with overrides and list them. This exposes a test-design mistake before the answer is interpreted.

Section sources:[1] Perplexity

The following checklist is an editorial working artifact derived from the documented distinctions. It checks whether conditions are recorded completely; its effectiveness has not been measured experimentally. Apply it before starting a series and whenever deliberately moving to another configuration.

• Record the objective: follow the current service or compare a pinned configuration.
• Save the invocation method: dynamic name, returned version, or complete explicit field set.
• For effort, preserve the submitted value, version from the initial response, and every override.
• For an explicit request, verify model, tools, instructions, parameters, and absence of effort; mark unavailable settings.
• Preserve exact requests, submitted dated instructions, execution time, full responses, and errors.
• Define the answer-comparison rule in advance; record every configuration change as a separate condition.

Section sources:[1] Perplexity

GeoAeoAle Editorial verified the supplied public snapshot’s SHA-256 and examined definitions, version syntax, override rules, and explicit-configuration limitations. The source check date is 2026-10-27. The comparison of invocation methods uses one document; no API requests or historical snapshot comparison were performed.

Full texts of potentially overlapping published pages were used only for duplicate checking and related-page selection. The existing Fast Search audit concerns returned pages and fact use, while measurement guides concern test conditions and outcomes. This page has a narrower task: choosing and verifying Agent API configuration pinning. Other batch proposals address different tasks; no prepared peer candidate texts were present.

Our bounded inference is that pinning helps control the configuration component of an evaluation. It does not preserve a web snapshot or establish identical answers. The next action is to complete the checklist and verify your own run. Original copy and the checklist are licensed CC BY 4.0; the source remains subject to its own terms.

Section sources:[1] Perplexity