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.
Connect Perplexity to Mattering
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
Perplexity: List Models succeeds even though the key is wrong
A sonar-deep-research run times out on the chat node
Perplexity: Get Async Chat Completion returns an empty response field
Embedding vectors come back as unreadable strings
Perplexity: Search the Web spent money on what looks like a read
Chat responses never stream
A chat call cost more than the tokens explain
Related
The Perplexity MCP
What connecting Perplexity unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.