Profiles

A profile is a reusable, versioned configuration that you save and manage. It bundles the settings that shape a run, including the model or model fallback chain, system instructions, reasoning effort, tools, Skills, managed connectors, and the agent loop step budget, under a single ID. Select a profile by ID instead of repeating the full configuration in every request.

A profile is the counterpart to a preset that you control. A preset is a configuration that Perplexity maintains and tunes. A profile is a configuration that you define and version.

1. Open Profiles in the API Portal.
2. Select Create profile.
3. Set the model, instructions, tools, Skills, and managed connectors the profile should use, then save it.
4. Copy the profile ID.
5. Add a profile entry to the Agent API request. Set type to "custom" and id to the profile ID, and do not set preset in the same request.

The run uses the profile's model, instructions, tools, Skills, managed connectors, and other settings, so you do not repeat them. The following request runs a profile. Replace profile_YOUR_PROFILE_ID with the ID that you copied.

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    profile={
        "type": "custom",
        "id": "profile_YOUR_PROFILE_ID",
    },
    input="Summarize this week's most important AI research.",
)

print(response.output_text)

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

const client = new Perplexity();

const response = await client.responses.create({
  profile: {
    type: 'custom',
    id: 'profile_YOUR_PROFILE_ID',
  },
  input: "Summarize this week's most important AI research.",
});

console.log(response.output_text);

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "type": "custom",
      "id": "profile_YOUR_PROFILE_ID"
    },
    "input": "Summarize this weeks most important AI research."
  }' | jq

A profile supplies the defaults for a run. Any parameter you set on the request overrides the profile's value for that field, so you can reuse one profile and adjust a single setting per request. For example, pass model to run the profile's configuration with a different model, while keeping its instructions, tools, and other settings.

tools are the exception: they merge per tool instead of replacing the whole set. Listing one tool overrides only that tool's options and leaves the profile's other tools enabled.

Each version of a profile is immutable: editing a profile creates a new version instead of changing an existing one. A request pinned to a specific version always runs the exact same configuration, so only "latest" picks up new versions. The version is resolved when the request is admitted, so a change made while a request is in flight does not affect that run.

Pin production traffic to a specific version:

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    profile={
        "type": "custom",
        "id": "profile_YOUR_PROFILE_ID",
        "version": "3",
    },
    input="Summarize this week's most important AI research.",
)

print(response.output_text)

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

const client = new Perplexity();

const response = await client.responses.create({
  profile: {
    type: 'custom',
    id: 'profile_YOUR_PROFILE_ID',
    version: '3',
  },
  input: "Summarize this week's most important AI research.",
});

console.log(response.output_text);

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "type": "custom",
      "id": "profile_YOUR_PROFILE_ID",
      "version": "3"
    },
    "input": "Summarize this weeks most important AI research."
  }' | jq

With "latest", a version uploaded by any Admin immediately changes what your production requests run. View version history and download any version in the API Portal.

A profile problem fails the request with a 4xx status before the run starts, so handle it like any other request error. The cases you may see:

• The profile names a model you cannot use. The request fails with model "<model>" is not supported. Edit the profile to use a supported model.
• The profile ID is wrong, or you cannot access it. The request fails with The requested profile does not exist or is not accessible. Check the ID.
• The version is not valid. Use a version that exists, or "latest".

Manage your profiles in Profiles in the API Portal. If a problem persists, contact api@perplexity.ai.