How to retrieve a Phantom’s result files (CSV or JSON) via API

To retrieve a Phantom's result files via the PhantomBuster API, call GET /agents/fetch with the Agent ID to get the orgS3Folder and s3Folder values, then build the download URL: https://phantombuster.s3.amazonaws.com/orgS3Folder/s3Folder/result.csv (or result.json). The API doesn't return the file directly, it returns metadata you use to construct the download link.

Looking for results from one specific launch? The /agents/fetch endpoint covered in this guide returns the latest aggregated results for a Phantom. If you need the output of a single launch (tied to a specific Container ID), use the Containers endpoint instead - see How to retrieve the result object for a specific Phantom launch via API.

Before you start

Before retrieving Phantom results via API, make sure that:

• The Phantom has already been launched at least once.
• You have a valid PhantomBuster API key.
  → If you don't have one, see Create an API key. API keys can only be created by workspace admins - if you don't see the Add API key button, check with your admin.
• You know the Agent ID of the Phantom whose results you want to retrieve.

→ If any of these are missing, start with How to Get Started with the PhantomBuster API.

How retrieving result files via API works

When a Phantom runs, it generates result files (CSV and JSON). The API doesn't send those files directly in the response.

Instead, the API:

• Tells you where the files are stored.
• Lets you build a download link.
• Allows you to download the files from your browser or your own tool.

Retrieve Phantom result files from the API reference

Step 1: Open the results endpoint

1. Open the PhantomBuster API reference.

2. In the left menu, go to:

   PhantomBuster API v2 → Agents → GET /agents/fetch → This is the endpoint PhantomBuster uses to retrieve information about a Phantom, including where its result files are stored.

Step 2: Add your API key

1. In the top-right corner of the page, locate the Credentials section.
2. In the header field labeled X-Phantombuster-Key, paste your API key.

Step 3: Add the Agent ID

1. In the Query Params section, find the field named id.
2. Paste the Agent ID of the Phantom whose results you want to retrieve (see How to find your Agent ID for API calls).

Step 4: Send the request

• Click Try It! If the request is successful, the API response will appear below.

  

  → This response doesn't contain the results themselves, but it contains information you'll use to download them.

Step 5: Identify the result file locations

• If the request is successful:
  • The API returns a 200 status.
  • The response includes metadata about the Phantom, including where its result files are stored.
• In the API response, look for these two fields:
  • orgS3Folder → This identifies your Workspace's storage location.
  • s3Folder → This identifies the storage folder for this Phantom.

→ These values act like parts of a file address, you'll use them to build a download link.

Step 6: Build the download link

The API does not download the file for you automatically, you manually construct the download URL using the values from the response.

Here's how to do it:

1. Start from the base download URL

Most Phantoms generate their results using the default file names such as result.csv and result.json.

• CSV file

https://phantombuster.s3.amazonaws.com/orgS3Folder/s3Folder/result.csv

• JSON file

https://phantombuster.s3.amazonaws.com/orgS3Folder/s3Folder/result.json

→ If your Phantom uses a different result file name, you'll need to replace result.csv and result.json with the correct file name.

2. Replace the folder values

From Step 5, copy the values shown in the API response:

• orgS3Folder
• s3Folder

Now replace them directly in the URL, keeping the slashes and removing any quotes.

Example:

If the API response shows:

• orgS3Folder: E5czzj975lU
• s3Folder: BIcIPWVRhDy3pjF04LyTtw

→ Your final CSV download link becomes:

https://phantombuster.s3.amazonaws.com/E5czzj975lU/BIcIPWVRhDy3pjF04LyTtw/result.csv

3. Open the link to download the file

• Paste the completed URL into your browser address bar.
• Press Enter.

→ The file will download immediately, just like a normal file download.

Frequently asked questions

Why doesn't the API return the result file directly?

The API returns metadata about where the file is stored. You use the orgS3Folder and s3Folder values to build a download URL. This is how PhantomBuster's storage works, results are hosted on S3.

What if my Phantom uses a custom result file name?

Replace result.csv or result.json in the download URL with the actual file name your Phantom uses. You can check the file name in your Phantom's results settings.

How do I get results from one specific launch?

Use the Containers endpoint instead of /agents/fetch. This lets you retrieve results tied to a specific Container ID (launch ID). See How to retrieve the result object for a specific Phantom launch via API.

Can I automate the download in my own tool?

Yes. Build the download URL programmatically using the orgS3Folder and s3Folder values from the API response, then fetch the file with a standard HTTP GET request.