Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt

Use this file to discover all available pages before exploring further.

Sandbox is in preview. Runtime availability, quotas, and pricing may change.

​
Overview

The sandbox tool lets the model run code during an Agent API request. The agent can execute code in an isolated container, inspect the output, and use the result in its final answer. Enable the tool by adding it to the tools array. The model decides when to call it based on your prompt and instructions. 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.5",
    input="Create a CSV with the first 10 Fibonacci numbers and their squares.",
    tools=[{"type": "sandbox"}],
    instructions="Use the sandbox to compute the values before answering.",
)

print(response.output_text)

​
Use cases

  • Web search
  • Numeric calculations and statistical analysis
  • Data cleaning, parsing, and transformation
  • Code execution to check logic or reproduce an error
  • Structured artifact generation, such as CSV, JSON, or reports
  • Multi-step workflows that need intermediate files or computed state

​
Running in the background

For long-running sandbox calls, submit the request with background: true and poll the response by ID until it completes. 
import time
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.5",
    input="Create a CSV with the first 10 Fibonacci numbers and their squares.",
    tools=[{"type": "sandbox"}],
    background=True,
)

while response.status in ("queued", "in_progress"):
    time.sleep(2)
    response = client.responses.retrieve(response.id)

print(response.output_text)

​
Error handling

Sandbox errors are returned through the normal Agent API response.
CaseWhat you see
TimeoutThe status on the affected entry in results[] (and on the enclosing sandbox_results item) is timed_out. If the request cannot complete, the top-level response status is failed with an error object.
Runtime errorThe matching entry in results[] includes a non-zero exit_code and error output in stderr. The Agent API response may still complete if the container ran successfully.
Quota or limitThe response fails with an error object describing the limit. Agent API rate limits still apply.

​
Limits and quotas

Sandbox runs inside Agent API requests and is subject to Agent API rate limits. See Rate Limits & Usage Tiers for tier-based request limits.

​
Response shape

When the model calls the sandbox tool, the Agent API response includes a sandbox_results item in its output array alongside any message items. A single response can contain multiple sandbox_results items if the model makes more than one sandbox call. Each sandbox_results item describes one sandbox invocation and nests the per-execution output inside a results array.
FieldTypeDescription
typestringAlways sandbox_results.
call_idstringIdentifier for this sandbox tool call.
container_idstringIdentifier of the isolated container that executed the code.
languagestringLanguage the sandbox ran the code in (for example, python).
codestringThe code that was executed inside the sandbox.
statusstringOverall status of the sandbox call. One of completed, timed_out, failed.
resultsarrayOne entry per execution inside the container. See fields below.
Each entry in results has the following fields:
FieldTypeDescription
stdoutstringStandard output captured from the execution.
stderrstringStandard error captured from the execution.
exit_codeintegerProcess exit code. Non-zero indicates a runtime error.
duration_msintegerWall-clock duration of the execution, in milliseconds.
statusstringPer-execution status. One of completed, timed_out, failed.
Example: 
{
  "type": "sandbox_results",
  "call_id": "call_Y1Lo4H6cGFgNVsn4mwC0oSgc",
  "code": "vals = [(i, i*i) for i in range(1, 11)]\nprint('\\n'.join(f'{a},{b}' for a, b in vals))",
  "container_id": "i6dr97ven2qfm0sdtvfzc",
  "language": "python",
  "results": [
    {
      "duration_ms": 9011,
      "exit_code": 0,
      "status": "completed",
      "stderr": "",
      "stdout": "1,1\n2,4\n3,9\n4,16\n5,25\n6,36\n7,49\n8,64\n9,81\n10,100\n"
    }
  ],
  "status": "completed"
}
For the full request and response schema, see the Agent API reference.

​
Pricing

sandbox is billed on three axes:
AxisPriceNotes
TokensPer modelModel token usage is billed separately according to Agent API token pricing. See Models for per-model rates.
Sandbox session$0.03 per sessionBilled once per sandbox container. A session is the lifecycle of a single isolated container and covers up to 20 minutes of active use for billing purposes — this is the billing window, not a runtime cap.
Tools usedPer toolCode running inside the sandbox can call the Web Search, Fetch URL Content, and People Search tools. Each is billed at its standard per-invocation rate.
Sandbox invocations are counted under usage.tool_calls_details.sandbox.invocation. See Pricing for the full Agent API tool pricing table.