Menu

Mattering Automations Perplexity integration

Connect Perplexity to Mattering Automations: search-grounded sonar answers with citations, raw web search with page content, async deep research jobs, and embeddings as workflow steps, authenticated with a Perplexity API key.

The Mattering Automations Perplexity integration adds Perplexity to your automation canvas: ask sonar models questions answered with live web search and returned with citations and per-source search results, run raw web searches with extracted page content, submit long deep research jobs asynchronously and poll for the finished report, and create plain or contextualized embeddings.

Setup takes a few minutes: create an API key in the Perplexity console, attach it as a credential in Mattering, and test the connection. The API has no free tier, but the connection test uses the one authenticated endpoint that is free to call, so verifying a key costs nothing. This guide walks through each step and ends with the full node reference.

Spend visibility is built in rather than bolted on. Every response includes a usage.cost breakdown in USD covering token costs, the per-request search fee on chat, and on deep research runs the citation, reasoning, and search query costs. The billing mechanisms by surface: chat is per token plus a per-request search fee tiered by search context size, the Search API is a flat price per request, and embeddings are per token.

Before you start

  • A Perplexity account with access to the API console at console.perplexity.ai.
  • Perplexity API billing in place: the API is pay as you go with no free tier or trial credits, so paid nodes bill from their first call. The connection test itself is free.
  • A Mattering workspace with access to the Automations app.

Create a Perplexity API key

Mattering authenticates to Perplexity with an API key, sent as a bearer credential on every request. Keys are created in the Perplexity API console; there is no OAuth flow.

Open the Perplexity console at console.perplexity.ai and go to API Keys.
Create a new API key.
Copy the key.
Perplexity's API has no free tier or trial credits: every chat, search, and embeddings call bills from its first run. The two async read nodes, the model list, and the connection test are the only free calls. Every response includes a usage.cost breakdown in USD, so workflows can log spend per run.

Connect Perplexity to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Perplexity from the list.
Click Create new credential, paste your API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering lists your asynchronous chat jobs, the one authenticated Perplexity endpoint that is free to call, so the check confirms the key without spending anything.
Click Connect. All 8 Perplexity nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Perplexity section should list the query and action nodes. Drop Perplexity: List Async Chat Completions onto the canvas and run a test step. It takes no parameters, its config panel is intentionally empty, and it is the connector's free credential check: a valid key returns your async job list, usually empty, at no cost, while a bad key fails with a 401. Do not use Perplexity: List Models to verify a key: that endpoint requires no authentication, so it succeeds even with a wrong key.

For a first end-to-end check, run Perplexity: Chat Completion (Sonar) with a short question on the default sonar model. A successful response carries the answer at data.choices[0].message.content, source URLs at data.citations, per-source detail with title, url, date, and snippet at data.search_results, and the cost of the call itself at data.usage.cost. This is a paid call, billed per token plus the per-request search fee, but a one-line question on sonar keeps it small.

Node reference

8 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 4

Perplexity: Get Async Chat Completion

perplexity_get_async_chat

Fetch one asynchronous chat completion job by id. While data.status is CREATED or IN_PROGRESS the response field is empty; once COMPLETED, data.response holds the full completion (answer, citations, search_results, usage with cost), and on FAILED data.error_message says why. Free to call; poll this after the create node.

Perplexity: List Async Chat Completions

perplexity_list_async_chats

List your recent asynchronous chat completion jobs with their status and timestamps at data.requests. Free to call and read-only, which makes it the connector's credential health check: a bad key gets a 401, a good key gets a 200 at no cost. The endpoint takes no parameters, so the config panel is intentionally empty.

Perplexity: List Models

perplexity_list_models

List the model catalog for Perplexity's Agent API in the OpenAI list format (ids like anthropic/claude-sonnet-4-6 or openai/gpt-5.5). Honest scope note: this does NOT list the sonar chat models - those are the fixed sonar family named in the chat node's model field. Free; the endpoint requires no authentication, so it also cannot verify your key. The endpoint takes no parameters, so the config panel is intentionally empty.

Perplexity: Search the Web

perplexity_search

Run Perplexity's raw web search and get ranked results with extracted page content, without invoking a model. Each item in data.results carries title, url, snippet, date, and last_updated. Read-only but PAID: billed at a flat per-request price, which is why its Test Class is not Safe Read. Path note: this endpoint is /search with no /v1 prefix.

Action nodes 4

Perplexity: Chat Completion (Sonar)

perplexity_chat_completion

Ask a Perplexity sonar model a question answered with live web search. The response carries the answer at data.choices[0].message.content, the source URLs at data.citations, rich per-source detail (title, url, snippet, dates) at data.search_results, and token usage with a USD cost breakdown at data.usage. Billed per token plus a per-request search fee tiered by search context size. Streaming is always off: the node returns one JSON response.

Perplexity: Create Async Chat Completion

perplexity_create_async_chat

Submit a sonar chat completion as an asynchronous job and get back a request id immediately, instead of holding the connection open. Built for sonar-deep-research runs that take minutes. Poll the id with the Get Async Chat Completion node until data.status is COMPLETED, then read the full completion from data.response. Billing is identical to the synchronous node.

Perplexity: Create Contextualized Embeddings

perplexity_create_contextualized_embedding

Embed document chunks so each chunk's vector also encodes its document-level context, improving RAG retrieval over plain chunk embeddings. Send a JSON array of documents, each a list of chunk strings, and get the same nested shape back at data.data[doc].data[chunk].embedding (base64-encoded, like the plain embeddings node). Billed per input token.

Perplexity: Create Embeddings

perplexity_create_embedding

Turn text into embedding vectors with a Perplexity pplx-embed model. Send one string or a JSON array of strings, get one vector per input at data.data[i].embedding. Note the vectors come back BASE64-ENCODED (int8 or packed binary), not as plain JSON float arrays; downstream consumers must decode them. Billed per input token, reported at data.usage.

Using the integration

On the automation canvas

Perplexity nodes chain with every other node: a research question on a task in Mattering Productivity can come back as a cited answer in the task's comments, Perplexity: Search the Web can feed extracted page content into a summarization step, and each response's usage.cost total can append to a Mattering database so the team sees research spend per run.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can ask search-grounded questions, run raw searches, and poll deep research jobs through the same nodes your workflows use, and every answer arrives with citations a person can check.

Citations and search results are first-class outputs

The reason to route an automation through Perplexity instead of a plain LLM is that answers arrive with their sources. On Perplexity: Chat Completion (Sonar) the answer sits at data.choices[0].message.content, plain source URLs at data.citations, and per-source detail (title, url, date, snippet) at data.search_results, all usable as output paths in downstream steps. Optional toggles add images and related questions to the response.

The async pattern for deep research

Perplexity: Create Async Chat Completion takes the whole chat request as one request object and returns a request id immediately with status CREATED. Put a delay after it, then Perplexity: Get Async Chat Completion polls the id until data.status reaches COMPLETED and the full completion appears at data.response; a FAILED job explains itself in data.error_message. The synchronous chat node can run sonar-deep-research too, but it carries a 300 second timeout, so the create, delay, poll shape is the right one for reports that take minutes. Polling is free; billing on the job itself is identical to the synchronous node.

Costs you can see per run

Perplexity's API is pay as you go with no free tier. Chat completions bill per input and output token plus a per-request search fee tiered by search context size; deep research adds citation tokens, reasoning tokens, and per-search fees; the Search API bills a flat price per request; embeddings bill per input token. Every response reports its own cost at data.usage.cost with an itemized USD breakdown and a total, so a workflow can log spend without estimating anything.

Models are plain config fields

The model on every node is a free-text field with a documented default, so new Perplexity models work without a connector update. The chat family today is sonar (the default), sonar-pro, sonar-reasoning-pro, and sonar-deep-research; Perplexity: Create Embeddings defaults to pplx-embed-v1-0.6b and Perplexity: Create Contextualized Embeddings to pplx-embed-context-v1-0.6b. Note that Perplexity: List Models lists the catalog for Perplexity's separate Agent API, not the sonar chat family.

Troubleshooting

Test Connection fails with a 401
The key is invalid, was revoked, or picked up stray whitespace when pasted. Create a fresh key on the API Keys page in the Perplexity console and update the credential on the connector. The test itself is free, so retry as often as needed.
Perplexity: List Models succeeds even though the key is wrong
That endpoint requires no authentication, so it returns results regardless of the credential and verifies nothing. Use Test Connection or Perplexity: List Async Chat Completions to check a key: both are free, and a bad key fails them with a 401.
A sonar-deep-research run times out on the chat node
Perplexity: Chat Completion (Sonar) holds the connection open and carries a 300 second timeout, and deep research reports can take longer than that. Submit the same request through Perplexity: Create Async Chat Completion instead, then poll Perplexity: Get Async Chat Completion until data.status is COMPLETED. Billing is identical; only the delivery shape changes.
Perplexity: Get Async Chat Completion returns an empty response field
The job has not finished. While data.status is CREATED or IN_PROGRESS the data.response field is empty by design; keep polling, with a delay between attempts, until it reaches COMPLETED. If the status is FAILED, data.error_message says why. Polling is free, so a patient loop costs nothing.
Embedding vectors come back as unreadable strings
That is the documented format, not corruption. Perplexity returns each vector base64 encoded, as signed int8 by default or packed bits with the binary option, never as plain JSON float arrays, so the consuming step or service must decode them. The upside is that execution records stay small even for large batches; the documented limits are 512 texts per request and 32K tokens per text.
Perplexity: Search the Web spent money on what looks like a read
That is its pricing working as documented: the Search API bills a flat price per request, with no free allowance, even though the call has no side effects. This is why the node is classed as a paid call for testing rather than a safe read. Budget for it like any other paid step and read the actual charge from the response's usage cost fields.
Chat responses never stream
By design. The integration pins streaming off on the chat body and inside the async request object, and workflow config cannot re-enable it: a canvas step consumes one JSON response per execution. The node returns the finished answer with citations, search results, and usage in a single payload.
A chat call cost more than the tokens explain
Chat completions bill a per-request search fee on top of tokens, tiered by search context size, and deep research runs add citation tokens, reasoning tokens, and per-search fees. The data.usage.cost breakdown itemizes each component in USD, so read it to see exactly where the spend went. Lowering the search context size, keeping max_tokens modest, choosing sonar over the larger models, or disabling search on calls that do not need it, which skips the search fee entirely, are the levers.

Perplexity is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products