The Perplexity connector lets your AI agent act in each user's Perplexity account. Each user connects their own Perplexity access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 17 tools.
- Tools
- 17
- What they doRead · write · destructive
- 13 · 4 · 013 read4 write0 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Perplexity connection
In AgentKit > Connections, create a Perplexity connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'perplexity'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Perplexity:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'perplexity_list_async_chat_completions',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "perplexity"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Perplexity:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="perplexity_list_async_chat_completions",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Perplexity credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolperplexity_answer_decisionsEvaluate named yes/no, multiple-choice, and scoring questions against a piece of content.Read-onlyAnswer Decisions
Evaluate named yes/no, multiple-choice, and scoring questions against a piece of content. Returns an answers object keyed by question name (probability for noul, chosen option for choice, level for score), plus the model and token usage. Use this for classification, moderation, routing, and rubric scoring over text; use perplexity_chat_completion for open-ended answers.
Inputs
modelstringrequired- Decision model: pplx-decider-v1.2 (larger) or pplx-decider-flash-v1.2 (faster, cheaper). Aliases pplx-decider-latest and pplx-decider-flash-latest also work.
questionsobjectrequired- Questions as a JSON object mapping a name you choose to a question. Each question has a type of noul (yes/no, with instructions), choice (with criteria mapping option names to descriptions), or score (with criteria listing level descriptions). Example: {"is_bug":{"type":"noul","instructions":"Is this a bug report?"},"area":{"type":"choice","criteria":{"billing":null,"settings":null}}}
statestringrequired- The content every question refers to: plain text, or a JSON object or array serialized as a string. Example: Customer wrote: the app crashes every time I open settings.
perplexity_create_contextualized_embeddingsGenerate document-aware embeddings for chunks, where each chunk is encoded with the context of its sibling chunks.Read-onlyCreate Contextualized Embeddings
Generate document-aware embeddings for chunks, where each chunk is encoded with the context of its sibling chunks. Returns a data array with one entry per document holding its chunk embeddings (base64-encoded), plus model and token usage. Use this for chunked documents in retrieval pipelines; use perplexity_create_embeddings for independent texts.
Inputs
inputarrayrequired- Documents as a JSON array of arrays: each inner array holds the ordered chunk strings of one document (max 512 documents, 16,000 chunks total). Example: [["intro chunk","body chunk"],["other doc chunk"]]
modelstringrequired- Contextualized embedding model: pplx-embed-context-v1-0.6b (up to 1024 dimensions) or pplx-embed-context-v1-4b (up to 2560 dimensions).one of
pplx-embed-context-v1-0.6bpplx-embed-context-v1-4b dimensionsinteger- Output dimensions (128-1024 for the 0.6b model, 128-2560 for the 4b model). Defaults to the model full size. Example: 512
encoding_formatstring- Encoding of returned vectors: base64_int8 (default) or base64_binary (1 bit per dimension).one of
base64_int8base64_binary
perplexity_create_embeddingsGenerate text embeddings for one or many independent texts.Read-onlyCreate Embeddings
Generate text embeddings for one or many independent texts. Returns a data array with one embedding per input (base64-encoded), plus model and token usage. Use this for independent texts such as queries or sentences. Use perplexity_create_contextualized_embeddings for chunks that belong to the same document.
Inputs
inputarrayrequired- Texts to embed, as a JSON array of 1-512 non-empty strings. Total must stay under 120,000 tokens. Example: ["first passage","second passage"]
modelstringrequired- Embedding model: pplx-embed-v1-0.6b (up to 1024 dimensions) or pplx-embed-v1-4b (up to 2560 dimensions).one of
pplx-embed-v1-0.6bpplx-embed-v1-4b dimensionsinteger- Output dimensions (128-1024 for the 0.6b model, 128-2560 for the 4b model). Defaults to the model full size. Example: 512
encoding_formatstring- Encoding of returned vectors: base64_int8 (default) or base64_binary (1 bit per dimension).one of
base64_int8base64_binary
perplexity_get_agent_responseFetch one Agent API response by id, including its current status.Read-onlyGet Agent Response
Fetch one Agent API response by id, including its current status. Returns id, status, model, output items, error details if any, and token usage. Use this to poll a background run or re-read a stored response. Requires the response id returned by perplexity_create_agent_response.
Inputs
idstringrequired- Id of the agent response, as returned by perplexity_create_agent_response (starts with resp_). Example: resp_abc123
perplexity_get_async_chat_completionFetch the status and result of one async chat completion job by id.Read-onlyGet Async Chat Completion
Fetch the status and result of one async chat completion job by id. Returns id, model, status, created/started/completed/failed timestamps, error_message, and the full response once finished. Use this to poll a job created with perplexity_create_async_chat_completion; use perplexity_list_async_chat_completions to find job ids. Requires the job id returned when the job was created.
Inputs
api_requeststringrequired- Id of the async chat completion job, as returned by perplexity_create_async_chat_completion or perplexity_list_async_chat_completions. Example: 7d1a2b3c-4e5f-6789-abcd-0123456789ab
perplexity_get_skillGet one custom skill by id, optionally at a specific revision.Read-onlyGet Skill
Get one custom skill by id, optionally at a specific revision. Returns skill_id, name, description, revision, latest_revision, and created/updated timestamps. Use this for one skill's metadata; use perplexity_list_skill_revisions for its history. Requires a skill id from perplexity_list_skills.
Inputs
skill_idstringrequired- Id of the skill, as returned by perplexity_list_skills. Example: skill_abc123
revisionstring- Revision id to fetch; defaults to the latest revision. Example: rev_001
perplexity_get_skill_download_urlGet a download URL for a custom skill's package, optionally for a specific revision.Read-onlyGet Skill Download URL
Get a download URL for a custom skill's package, optionally for a specific revision. Returns revision, name, and a download_url to fetch the package from. Use this to retrieve a skill's files; use perplexity_get_skill for metadata only. Requires a skill id from perplexity_list_skills.
Inputs
skill_idstringrequired- Id of the skill, as returned by perplexity_list_skills. Example: skill_abc123
revisionstring- Revision id to download; defaults to the latest revision. Example: rev_001
perplexity_list_agent_response_filesList the files an Agent API response generated, such as sandbox outputs.Read-onlyList Agent Response Files
List the files an Agent API response generated, such as sandbox outputs. Returns a data array of file records, each with a file id and metadata. Use this to see what a finished run produced. Requires the response id from perplexity_create_agent_response.
Inputs
idstringrequired- Id of the agent response, as returned by perplexity_create_agent_response (starts with resp_). Example: resp_abc123
perplexity_list_async_chat_completionsList async chat completion jobs submitted with your API key.Read-onlyList Async Chat Completions
List async chat completion jobs submitted with your API key. Returns a requests array with each job's id, model, status, and timestamps, plus a next_token. Use this to find job ids; use perplexity_get_async_chat_completion to read one job's full result.
Inputs
This tool takes no inputs.
perplexity_list_modelsList the models available to the Agent API.Read-onlyList Models
List the models available to the Agent API. Returns a data array of model objects whose ids can be passed as model to perplexity_create_agent_response. Use this before creating an agent response when you need a valid model id.
Inputs
This tool takes no inputs.
perplexity_list_skill_revisionsList the revisions of a custom skill.Read-onlyList Skill Revisions
List the revisions of a custom skill. Returns a revisions array and next_page_token. Use this to see a skill's history; use perplexity_get_skill for the current metadata. Requires a skill id from perplexity_list_skills.
Inputs
skill_idstringrequired- Id of the skill, as returned by perplexity_list_skills. Example: skill_abc123
limitinteger- Maximum items to return (1-200). Example: 50
page_tokenstring- Pagination cursor: the next_page_token from a previous response. Omit for the first page.
perplexity_list_skillsList the custom skills in your Perplexity project, newest first.Read-onlyList Skills
List the custom skills in your Perplexity project, newest first. Returns a skills array with each skill's id, name, description, and revision, plus next_page_token. Use this to find skill ids; use perplexity_get_skill for one skill's detail.
Inputs
limitinteger- Maximum items to return (1-200). Example: 50
page_tokenstring- Pagination cursor: the next_page_token from a previous response. Omit for the first page.
perplexity_searchSearch the web and return ranked results with page titles, URLs, snippets, and dates.Read-onlySearch the Web
Search the web and return ranked results with page titles, URLs, snippets, and dates. Returns a results array plus a request id; each result carries title, url, snippet, date, and last_updated. Use this for raw ranked results you will read yourself. Use perplexity_chat_completion or perplexity_create_agent_response for a synthesized answer with citations.
Inputs
querystringrequired- Search query text. For several related searches in one call, pass a JSON array of up to 5 query strings instead. Example: latest developments in solid-state batteries
countrystring- Two-letter ISO 3166-1 alpha-2 country code to bias results toward. Example: US
last_updated_after_filterstring- Only return results last updated after this date, in MM/DD/YYYY format. Example: 01/15/2026
last_updated_before_filterstring- Only return results last updated before this date, in MM/DD/YYYY format. Example: 06/30/2026
max_resultsinteger- Maximum number of results to return (1-50). Values above 20 are only accepted with search_type "people". Default 10.
max_tokensinteger- Maximum total webpage content tokens to return across all results (1-1000000). Example: 25000
max_tokens_per_pageinteger- Maximum webpage content tokens to extract from each result page (1-1000000). Example: 2048
search_after_date_filterstring- Only return results published after this date, in MM/DD/YYYY format. Example: 01/15/2026
search_before_date_filterstring- Only return results published before this date, in MM/DD/YYYY format. Example: 06/30/2026
search_domain_filterarray- Restrict results to these domains (max 20), as a JSON array of domain strings. Example: ["nature.com","arxiv.org"]
search_language_filterarray- Restrict results to these languages (max 20), as a JSON array of two-letter ISO 639-1 codes. Example: ["en","de"]
search_recency_filterstring- Only return results published within this time window.one of
hourdayweekmonthyear search_typestring- Search mode: "web" for general web search (default), "fast" for lower-latency and lower-cost web search, "people" for people search.one of
webfastpeople
perplexity_cancel_agent_responseRequest cancellation of a running Agent API response.WriteCancel Agent Response
Request cancellation of a running Agent API response. Returns the response_id and status cancelling; the run stops shortly after, so poll perplexity_get_agent_response for the final status. Use this to stop a long background run. A run that already finished returns an error. Requires the response id from perplexity_create_agent_response.
Inputs
idstringrequired- Id of the agent response, as returned by perplexity_create_agent_response (starts with resp_). Example: resp_abc123
perplexity_chat_completionGenerate a web-grounded answer from a Sonar model for a conversation (non-streaming).WriteCreate Chat Completion
Generate a web-grounded answer from a Sonar model for a conversation (non-streaming). Returns the assistant message in choices, plus citations, search_results, token usage, and optional images and related_questions. Use this for quick cited answers. Use perplexity_create_agent_response for multi-step agentic work, perplexity_create_async_chat_completion for slow sonar-deep-research jobs, and perplexity_search for raw results.
Inputs
messagesarrayrequired- Conversation so far as a JSON array of message objects, each with a role (system, user, assistant, or tool) and a content string. End with a user message. Example: [{"role":"user","content":"What changed in the EU AI Act this year?"}]
modelstringrequired- Sonar model to use: sonar (fast, cheap), sonar-pro (deeper, more citations), sonar-reasoning-pro (step-by-step reasoning), or sonar-deep-research (long multi-step research, slow).one of
sonarsonar-prosonar-deep-researchsonar-reasoning-pro disable_searchboolean- When true, turns web search off and the model answers from its training data only.
enable_search_classifierboolean- When true, a classifier decides whether the query needs web search at all.
language_preferencestring- ISO 639-1 code for the preferred response language. Example: en
last_updated_after_filterstring- Only use sources last updated after this date, MM/DD/YYYY. Example: 01/15/2026
last_updated_before_filterstring- Only use sources last updated before this date, MM/DD/YYYY. Example: 06/30/2026
max_tokensinteger- Maximum number of completion tokens to generate (up to 128000). Example: 1024
reasoning_effortstring- How much effort the model spends reasoning (minimal, low, medium, high); applies to reasoning-capable models.one of
minimallowmediumhigh response_formatobject- Structured output control as a JSON object. Omit for plain text. For JSON output use {"type":"json_schema","json_schema":{"schema":{...}}}, where schema is a JSON Schema object.
return_imagesboolean- When true, include image results in the response.
return_related_questionsboolean- When true, include suggested follow-up questions.
search_after_date_filterstring- Only use sources published after this date, MM/DD/YYYY. Example: 01/15/2026
search_before_date_filterstring- Only use sources published before this date, MM/DD/YYYY. Example: 06/30/2026
search_domain_filterarray- Limit search to these domains as a JSON array of domain strings. Example: ["wikipedia.org","github.com"]
search_language_filterarray- Filter results by language as a JSON array of ISO 639-1 codes. Example: ["en","fr"]
search_modestring- Source of search results: web (default), academic for scholarly sources, or sec for SEC filings.one of
webacademicsec search_recency_filterstring- Only use sources published within this time window.one of
hourdayweekmonthyear stoparray- Stop sequences as a JSON array of strings; generation ends when one is produced. Example: ["END"]
temperaturenumber- Sampling randomness from 0 to 2; higher is more random. Example: 0.2
top_pnumber- Nucleus sampling cutoff from 0 to 1. Example: 0.9
web_search_optionsobject- Web search tuning as a JSON object, for example {"search_context_size":"high"} (low, medium, or high amount of search context).
perplexity_create_agent_responseRun the Perplexity Agent API on a question or task, with optional web search tools, reasoning control, and structured output (non-streaming).WriteCreate Agent Response
Run the Perplexity Agent API on a question or task, with optional web search tools, reasoning control, and structured output (non-streaming). Returns id, status, model, an output array of messages and tool calls, and token usage with cost. Use this for agentic, multi-step research; use perplexity_chat_completion for a quick cited Sonar answer. Set background to true and poll perplexity_get_agent_response for long runs. Provide either preset or model.
Inputs
inputstringrequired- The question or task for the agent as plain text. Example: Compare the pricing of the three largest cloud vector databases.
backgroundboolean- When true the call returns immediately with status queued; poll perplexity_get_agent_response until the status is terminal. Use for long runs.
instructionsstring- System instructions that set standing rules for the run. Example: Answer in three bullet points and cite sources.
language_preferencestring- ISO 639-1 code for the response language. Example: en
max_output_tokensinteger- Maximum number of tokens to generate. Example: 2048
max_stepsinteger- Maximum number of research loop steps (1-100); overrides the preset. Without a preset the default is 1. Example: 5
modelstring- Model id in provider/model format, for example anthropic/claude-sonnet-5-5. Required when preset is not provided; use perplexity_list_models for valid ids.
modelsarray- Fallback chain of model ids in provider/model format, tried in order until one succeeds; takes precedence over model. Example: ["openai/gpt-5.6-terra","anthropic/claude-sonnet-5-5"]
presetstring- Preset name that bundles a model, system prompt, and search settings, such as fast, low, medium, high, or xhigh. Required when model is not provided.
previous_response_idstring- Id of an earlier completed response to continue the conversation from. Example: resp_abc123
reasoningobject- Reasoning control as a JSON object with an effort of minimal, low, medium, high, xhigh, or max. Example: {"effort":"high"}
response_formatobject- Structured output as a JSON object: {"type":"json_schema","json_schema":{"name":"answer","schema":{...}}}, where name is 1-64 alphanumeric characters and schema is a JSON Schema object.
storeboolean- When false, the response is hidden from later retrieval; it can still be continued with previous_response_id. Default true.
temperaturenumber- Sampling temperature forwarded to the model. Example: 0.3
toolsarray- Tools the agent may use, as a JSON array of tool objects, each with a type such as web_search, fetch_url, finance_search, people_search, image_search, or sandbox. Example: [{"type":"web_search"},{"type":"fetch_url"}]
top_pnumber- Nucleus sampling cutoff forwarded to the model. Example: 0.9
perplexity_create_async_chat_completionSubmit a Sonar chat completion as a background job instead of waiting for the answer.WriteCreate Async Chat Completion
Submit a Sonar chat completion as a background job instead of waiting for the answer. Returns the job id, model, status, and timestamps; the finished answer appears in response once status is COMPLETED. Use this for long jobs such as sonar-deep-research. Poll with perplexity_get_async_chat_completion and browse jobs with perplexity_list_async_chat_completions.
Inputs
messagesarrayrequired- Conversation so far as a JSON array of message objects, each with a role (system, user, assistant, or tool) and a content string. End with a user message. Example: [{"role":"user","content":"What changed in the EU AI Act this year?"}]
modelstringrequired- Sonar model to use: sonar (fast, cheap), sonar-pro (deeper, more citations), sonar-reasoning-pro (step-by-step reasoning), or sonar-deep-research (long multi-step research, slow).one of
sonarsonar-prosonar-deep-researchsonar-reasoning-pro disable_searchboolean- When true, turns web search off and the model answers from its training data only.
enable_search_classifierboolean- When true, a classifier decides whether the query needs web search at all.
idempotency_keystring- Unique key so retries of the same submission do not create duplicate jobs. Example: report-2026-q3-eu-ai-act
language_preferencestring- ISO 639-1 code for the preferred response language. Example: en
last_updated_after_filterstring- Only use sources last updated after this date, MM/DD/YYYY. Example: 01/15/2026
last_updated_before_filterstring- Only use sources last updated before this date, MM/DD/YYYY. Example: 06/30/2026
max_tokensinteger- Maximum number of completion tokens to generate (up to 128000). Example: 1024
reasoning_effortstring- How much effort the model spends reasoning (minimal, low, medium, high); applies to reasoning-capable models.one of
minimallowmediumhigh response_formatobject- Structured output control as a JSON object. Omit for plain text. For JSON output use {"type":"json_schema","json_schema":{"schema":{...}}}, where schema is a JSON Schema object.
return_imagesboolean- When true, include image results in the response.
return_related_questionsboolean- When true, include suggested follow-up questions.
search_after_date_filterstring- Only use sources published after this date, MM/DD/YYYY. Example: 01/15/2026
search_before_date_filterstring- Only use sources published before this date, MM/DD/YYYY. Example: 06/30/2026
search_domain_filterarray- Limit search to these domains as a JSON array of domain strings. Example: ["wikipedia.org","github.com"]
search_language_filterarray- Filter results by language as a JSON array of ISO 639-1 codes. Example: ["en","fr"]
search_modestring- Source of search results: web (default), academic for scholarly sources, or sec for SEC filings.one of
webacademicsec search_recency_filterstring- Only use sources published within this time window.one of
hourdayweekmonthyear stoparray- Stop sequences as a JSON array of strings; generation ends when one is produced. Example: ["END"]
temperaturenumber- Sampling randomness from 0 to 2; higher is more random. Example: 0.2
top_pnumber- Nucleus sampling cutoff from 0 to 1. Example: 0.9
web_search_optionsobject- Web search tuning as a JSON object, for example {"search_context_size":"high"} (low, medium, or high amount of search context).
No tools match.
