Perplexity

Perplexity’s Agent API combines models with built-in web search. Requires @stigg/agent-sdk-js 0.7.14 or later.

Set up

Wrap either Perplexity’s own client, Perplexity from @perplexity-ai/perplexity_ai, or an OpenAI client whose baseURL points at Perplexity. The SDK recognizes both from the api.perplexity.ai address and selects the Perplexity recipe automatically.

import Perplexity from '@perplexity-ai/perplexity_ai';

const perplexity = stigg.wrap(new Perplexity({ apiKey: process.env.PERPLEXITY_API_KEY }));

await perplexity.responses.create({
  model,
  input,
  tools: [{ type: 'web_search' }],
  stiggContext: { customerId: 'customer-acme', entitlement: { currencyId: 'credits' } },
});

import OpenAI from 'openai';

const perplexity = stigg.wrap(
  new OpenAI({ baseURL: 'https://api.perplexity.ai/v1', apiKey: process.env.PERPLEXITY_API_KEY }),
);

await perplexity.responses.create({
  model,
  input,
  stiggContext: { customerId: 'customer-acme', entitlement: { currencyId: 'credits' } },
});

@perplexity-ai/perplexity_ai is ESM only. In a CommonJS project, load it with await import('@perplexity-ai/perplexity_ai').
With the OpenAI client, use the base URL with /v1.
Streamed calls are metered without extra options. The Agent API sends the usage of a streamed call on its response.completed event, and the SDK reads it from there. A stream that ends before Perplexity sends its usage isn’t reported, and it’s raised as a metering failure.
A Perplexity address the SDK does not recognize, such as a proxy in front of Perplexity, is metered with the OpenAI recipe. To meter it as Perplexity, pass the recipe yourself, as shown in Event names.

Perplexity ended support for Sonar Chat Completions on September 27, 2026. Use the Agent API’s responses.create, as shown above.

Event names

A client the SDK detects as Perplexity reports under the OpenAI event names, openai.responses.create and openai.chat.completions.create. Earlier versions of the SDK reported Perplexity calls under these names too, so meters that filter on them keep receiving usage. Each event also has a provider dimension set to perplexity, so a meter can filter Perplexity calls apart from OpenAI’s. If the stiggContext already sets a provider dimension, your value is kept. To report under Perplexity’s own event names, pass the recipe to wrap():

import { perplexityRecipe } from '@stigg/agent-sdk-js';

const perplexity = stigg.wrap(new Perplexity({ apiKey: process.env.PERPLEXITY_API_KEY }), {
  recipe: perplexityRecipe(),
});
// Reported as perplexity.responses.create and perplexity.chat.completions.create

If a meter in Stigg filters on an openai.* name for Perplexity traffic, add the perplexity.* name to it before you switch.

Counting `total_cost`

Perplexity states the price of each call in dollars, including per-call tool fees such as web_search and fetch_url, which token counts don’t cover. The recipe reports it as total_cost, a whole number, so by default it counts in millionths of a dollar: a call that cost $0.0052 is reported as 5200. If the feature or credit type you meter in Stigg uses a different unit, pass the recipe yourself with unitsPerDollar. For example, to report in hundredths of a cent:

const perplexity = stigg.wrap(new Perplexity({ apiKey: process.env.PERPLEXITY_API_KEY }), {
  recipe: perplexityRecipe({ unitsPerDollar: 10000 }),
});

A larger unit rounds each call up to a whole unit, so cheap calls are overcharged. Keep the default unless your pricing requires otherwise.

OpenRouter and LiteLLM report their price as cost, and Perplexity as total_cost. A meter that prices all three needs both names.

`perplexityRecipe` options

Option	Default	Description
`unitsPerDollar`	`1000000` (millionths of a dollar)	How many `total_cost` units make one dollar.
`estimate`	`() => 1`	The requested usage of the check before the call. See Enforcing a limit on cost.

What is reported

Perplexity returns a usage object with the tokens each call consumed and the price it charged. The wrapper reads these and reports them to Stigg as the metrics below. For details, see Perplexity’s Agent API docs.

Method	Event name, detected	Event name, recipe passed to `wrap()`
`responses.create`	`openai.responses.create`	`perplexity.responses.create`
`chat.completions.create`	`openai.chat.completions.create`	`perplexity.chat.completions.create`

Agent API (responses.create)

Metric	What it counts
`input_tokens`	Input tokens, including cache reads and writes
`output_tokens`	Output tokens
`cache_read_input_tokens`	Input tokens served from the cache
`cache_creation_input_tokens`	Input tokens written to the cache
`total_tokens`	All input and output tokens, as reported by the vendor
`total_cost`	The price Perplexity charged for the call, tool fees included, in micro-dollars by default. Set `unitsPerDollar` to match how your Stigg feature is defined.

Chat Completions (chat.completions.create)

Metric	What it counts
`prompt_tokens`	Input tokens
`completion_tokens`	Output tokens
`reasoning_tokens`	Reasoning tokens
`citation_tokens`	Tokens in the citations Perplexity added
`num_search_queries`	Web searches the call ran
`total_tokens`	All input and output tokens, as reported by the vendor
`total_cost`	The price Perplexity charged for the call, as above

Cache tokens are counted inside input_tokens. If you price both the input metric and the cache metrics, cached tokens are charged twice. total_tokens includes the other token counts, so price the total or the parts, never both. Each event also includes:

Reported	What it is
`provider` dimension	`perplexity`, unless the `stiggContext` sets its own `provider`.
Idempotency key	The Perplexity response ID, so a retried report is never counted twice.

When a call is free, total_cost is omitted and the token metrics are still reported. The price breakdown Perplexity returns, such as tool_calls_cost and the per-tool tool_calls_details, is included under the raw. prefix. Every usage field the vendor returns is also included, with a raw. prefix. See How usage is reported.

What is not covered

search.create, embeddings, contextualizedEmbeddings, decisions, async.chat.completions, batches and browser.sessions aren’t gated or metered. To meter one, write a recipe of your own.
A responses.create with background: true is gated but not metered. Its first response is queued and has no usage, and the later retrieve that returns the usage isn’t wrapped.

Introduction

Get started

Usage metering

Credits

Entitlements and access enforcement

Governance

AI agents

Architecture and deployment

Pricing and packaging

Customers, subscriptions and contracts

Workflows

Widgets

Developer tools

Account management

Security & compliance

Set up

Event names

Counting `total_cost`

`perplexityRecipe` options

What is reported

What is not covered

​Set up

​Event names

​Counting total_cost

​perplexityRecipe options

​What is reported

​What is not covered

Set up

Event names

Counting `total_cost`

`perplexityRecipe` options

What is reported

What is not covered