Working with Files

Overview

Agent runs can produce files such as CSV, JSON, JSONL, and reports in the sandbox. When code the model runs in the sandbox tool writes a file and delivers it with the share_file tool, the response output array includes a share_file item. The file content is not returned inline — retrieve it separately with the response files endpoints, using the response id.

Produce a file

Give the agent the sandbox tool and ask it to write a file. Here it generates a CSV of the latest AI news. Keep the resulting response.id — you use it to list and download the file.

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="xhigh",
    tools=[{"type": "sandbox"}],
    input=(
        "Find the 10 latest AI news stories and write them to ai_news.csv "
        "with columns: title, source, url, published_date. Deliver the file."
    ),
)

print(response.id, response.status)

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "xhigh",
    "tools": [{ "type": "sandbox" }],
    "input": "Find the 10 latest AI news stories and write them to ai_news.csv with columns: title, source, url, published_date. Deliver the file."
  }'

For runs that take a while, submit with background=true and poll before listing files. See Background mode.

List a response’s files

GET /v1/responses/{id}/files Use the response id from the run above to list the files it produced.

files = client.responses.files.list(response.id)

for file in files.data:
    print(file.id, file.filename, file.bytes)

curl https://api.perplexity.ai/v1/responses/$RESPONSE_ID/files \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY"

{
  "data": [
    {
      "bytes": 8002,
      "created_at": 1780923289,
      "filename": "ai_news.csv",
      "id": "9198548a-490b-4119-858f-fd3676b60319",
      "object": "file"
    }
  ],
  "object": "list"
}

Field	Type	Description
`id`	`string`	File identifier, used to download; distinct from response id.
`filename`	`string`	Name the sandbox gave the file.
`bytes`	`integer`	File size in bytes.
`created_at`	`integer`	Unix timestamp when created.
`object`	`string`	Always `file`.

Download a file

GET /v1/responses/{id}/files/{file_id}/content Use the file id to download its content. The file id is distinct from the response id.

This endpoint returns raw file bytes, not JSON. The response includes a Content-Type matching the file and a Content-Disposition: attachment header carrying the original filename.

file = files.data[0]

content = client.responses.files.content(
    file_id=file.id,
    response_id=response.id,
)
content.write_to_file(file.filename)

curl https://api.perplexity.ai/v1/responses/$RESPONSE_ID/files/$FILE_ID/content \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -o ai_news.csv

Full example

Create a run that writes a file, then list and download everything it produced.

Python

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="xhigh",
    tools=[{"type": "sandbox"}],
    input=(
        "Find the 10 latest AI news stories and write them to ai_news.csv "
        "with columns: title, source, url, published_date. Deliver the file."
    ),
)

for file in client.responses.files.list(response.id).data:
    content = client.responses.files.content(
        file_id=file.id,
        response_id=response.id,
    )
    content.write_to_file(file.filename)
    print(f"Downloaded {file.filename} ({file.bytes} bytes)")

Overview

Produce a file

List a response’s files

Download a file

Full example

Next Steps

Sandbox

Background mode

Wide Research

​Overview

​Produce a file

​List a response’s files

​Download a file

​Full example

​Next Steps

Sandbox

Background mode

Wide Research

Overview

Produce a file

List a response’s files

Download a file

Full example

Next Steps