Create a Perplexity project credential, install it in the environment that will run the application and verify a current Agent API call. Review billing controls before connecting background work.

Before you start

Perplexity’s official key guide requires an API project before creating the first credential. The console’s project controls connect keys, members, usage and billing. Use the account intended to own the application and verify the permissions needed to manage it. Official Perplexity documentation. Official Perplexity documentation.

Choose a purpose for the key and a safe label that will remain useful during rotation. Distinguish a local experiment from a deployed research worker in your own operating record. Record who owns the application and how to stop it. The secret itself belongs in a protected configuration surface, not in that record.

Review Perplexity billing categories and API credit and promotion conditions before making requests. A consumer subscription or access to a web interface should not be treated as proof of developer credit. Use the AI API cost calculator for supported token assumptions and keep the selected product’s other charges explicit.

Step-by-step: create the key

  1. Open the official API console and select or create the project intended to own the application.
  2. Review project billing and payment preferences, including whether automatic reload is enabled.
  3. Open API keys and create a credential with a descriptive purpose label.
  4. Save the full value immediately in the intended secret store; the official guide states it is shown only when created.
  5. Configure PERPLEXITY_API_KEY in the environment that will execute the request, then verify the small example below.

If you join an existing team, obtain the appropriate project access through its administrator. Avoid creating a separate account simply because a key control is not visible. First establish which project should own the workload and whether your role is expected to manage credentials or only run the application. Official Perplexity documentation.

Confirm the safe label in the key list and document the application that uses it. A useful setup note says which deployment reads PERPLEXITY_API_KEY and when that process loads its environment. It should not include a screenshot containing the key, a console identifier or billing details. If the value was not saved, create a replacement through the documented controls rather than expecting to retrieve it later. Official Perplexity documentation.

Set a spending limit / budget alerts

Inspect the actual billing controls in your project. The official guide documents credit balance, payment methods, usage and automatic reload. Do not infer a hard per-key budget from a feature provided by another platform. Treat automatic funding and application workload limits as separate decisions. Official Perplexity documentation.

For a bounded evaluation, define the maximum task set your application will dispatch and stop accepting more when that set is complete. Preserve queued work when the account cannot proceed, and require an explicit operating decision before resuming a large backlog. This makes a prototype’s behavior understandable even when the console does not offer the exact budget control you expected.

Review usage after the first representative task. A research response can include more than the final answer’s visible tokens, depending on product and configuration. Record the selected endpoint and charge categories with the test so you can explain the account’s consumption before opening the application to more users.

Verify the key: first call with cURL and Python

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset":"low","input":"Explain HTTP conditional requests briefly, using primary documentation and source references."}'
from perplexity import Perplexity

client = Perplexity()
response = client.responses.create(
    preset="low",
    input="Explain HTTP conditional requests using primary documentation. "
          "Keep the answer brief and include source references.",
)
print(response.output_text)

The examples use the current Agent API and native Python SDK. Set the environment variable before running them and install perplexityai for Python. The text and citations depend on the live result; the fragment below illustrates the response structure rather than a guaranteed answer. Official Perplexity documentation.

{"object":"response","status":"completed","output":[{"type":"message","content":[{"type":"output_text","text":"<generated answer>","annotations":[]}]}],"usage":{"total_tokens":"<reported>"}}

Follow the complete Perplexity Python tutorial to inspect output and handle a missing local setting. If you maintain Sonar, use its specific endpoint and response contract during migration. The official Sonar documentation states that Sonar support continues until September 27, 2026 and directs developers to the Agent API migration guide. Official Perplexity documentation.

Where to put the key

The examples read PERPLEXITY_API_KEY. Raw HTTP uses the bearer authorization header, while the native client reads the environment variable. Keep the credential on the server side of an application and apply your own user access checks before forwarding work to the provider. Official Perplexity documentation.

Do not place the key in browser-delivered JavaScript, public configuration or copied notebook output. A local environment variable is useful only if it remains outside the delivered application bundle. For a deployed service, use its secret-injection mechanism and confirm that the correct process receives the value when it starts.

When diagnosing configuration, check presence and variable spelling without displaying the secret. A shell session, editor, container and scheduled worker can load different environments. Establish which one made the failed request and inspect its safe configuration record. A console key existing somewhere in the account does not establish that the intended worker has it.

Common rejections

The SDK error guide distinguishes authentication, permissions, missing resources, rate limits and server failures. Save the safe status and exception class, then follow Perplexity error diagnosis. Do not repeatedly regenerate credentials before checking whether the failure concerns billing, a product route or a request field. Official Perplexity documentation.

For authentication, verify the environment and intended project. For permission errors, inspect project access and the actual safe response detail. For rate errors, review product-specific admission rules and shared workloads. For a request that returns an unexpected object, confirm the endpoint and SDK method; Agent and Sonar response parsing are different tasks.

Rotate and revoke

The official key guide documents both console and programmatic key management. For a controlled rotation, create the replacement, install it in the intended application, verify a harmless call and then revoke the old key after its legitimate users have migrated. Revoked values cannot be recovered. Official Perplexity documentation.

Keep safe labels and deployment times in the rotation record. Check background workers as well as the web service; they may reload secrets at different times. If a key was exposed, revoke it and review account activity. Removing the public copy does not restore trust in the old value. Return to the Perplexity API hub for the current integration and source references.

Frequently asked questions

Why must I create a project first?
The official key workflow starts with a project that owns API access and billing. Establish the intended project before generating a credential.
Can I reveal an existing key again later?
The official guide says the full value is shown at creation. Save it securely then; use a replacement if the value was not retained.
Does an API key include free inference?
A key authenticates access. Verify usable credit or an explicit offer in the project separately before relying on free traffic.
Why use Agent in the verification example?
The current platform directs Sonar integrations toward Agent and publishes a Sonar support deadline. The example establishes a current request baseline.
Can the same response parser handle Agent and Sonar?
Do not assume that. Follow the documented method and output structure for the selected product, including citation handling.
When should I revoke the old credential during rotation?
For a routine migration, verify the replacement in its legitimate applications first, then revoke the old key. Suspected exposure requires prompt revocation and activity review.

Sources

Last verified · Source ↗