How to list your Phantoms and get their Agent IDs via API

To list all your Phantoms and their Agent IDs via the PhantomBuster API, call GET /agents/fetch-all with your API key. This returns every Phantom in your workspace with its ID, name, and configuration. To get Agent IDs only for Phantoms that ran during a specific period, use GET /orgs/export-agent-usage with a time range (up to 6 months).

If you only need the Agent ID of one specific Phantom, you can find it in the Phantom’s URL after opening it from your Dashboard.
→ Learn how in How to find your Agent ID for API calls.

Before you start

Before retrieving Phantom Agent IDs via API, make sure:

• 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 what you want to retrieve:
  • A full list of all your Phantoms and their Agent IDs.
  • Agent IDs only for Phantoms that ran during a specific time range (up to 6 months).

The sections below explain both options.

How retrieving Agent IDs via API works

Phantom Agent IDs can be retrieved in two ways:

• By listing all Phantoms in your Workspace.
• By exporting usage data for a specific time range.

Both methods return Agent IDs that can be reused in other API calls, such as launching a Phantom, updating its configuration, or retrieving results.

Option 1: Get all Phantoms using the API reference

This method returns every Phantom in your Workspace along with its configuration details.

Step 1: Open the endpoint

1. Open the PhantomBuster API reference.

2. In the left menu, go to:

   PhantomBuster API v2 → Agents → GET /agents/fetch-all

→ This endpoint returns all Phantoms in your Workspace.

Step 2: Add your API key

1. In the top-right corner, locate the Credentials section.
2. In the Header, paste your API key into X-Phantombuster-Key.

Step 3: Send the request

• In the Request box on the right-hand side, click Try it to send the request.

  

• If the request is successful, the response returns:

  • A 200 status.
  • An array of Phantom objects in JSON format. 
    Each object includes:
    • id → The Phantom’s Agent ID.
    • name → The Phantom’s name in your Workspace.
    • Additional configuration fields such as script, branch, environment, and settings.

  

Option 2: Get Agent IDs from recent Phantom usage using the API reference

This method returns usage data for Phantoms that ran during a specific time range.

You can define how many days to look back. The maximum time range is 6 months.

Step 1: Open the endpoint

1. Open the PhantomBuster API reference.

2. In the left menu, go to:

   PhantomBuster API v2 → Orgs → GET /orgs/export-agent-usage

→ This endpoint exports usage data for Phantoms that ran during the selected time range.

Step 2: Add your API key

1. In the top-right corner, locate the Credentials section.
2. In the Header, paste your API key into X-Phantombuster-Key.

Step 3: Define the time range

• In the Query Params section, locate the days field (required), and enter the number of days you want to export. Make sure it does not exceed 6 months.

Step 4: Send the request

• In the Request box on the right-hand side, click Try it to send the request.

  

• If the request is successful, the response returns:

  • A 200 status.
  • The response contains usage data in CSV format. The file is returned as a downloadable CSV export.
  • The exported file includes columns such as:
    • Id → The Phantom’s Agent ID
    • Name → The Phantom’s name
    • Total launches
    • Total Execution Time In Seconds
    • Script Slug
    • Created At
    • Updated At
    • Deleted status

  

Frequently asked questions

What's the difference between /agents/fetch-all and /orgs/export-agent-usage?

/agents/fetch-all returns all Phantoms in your Workspace with full configuration details. /orgs/export-agent-usage returns a CSV with usage data (launches, execution time) only for Phantoms that ran during the specified time range.

Is there a limit to how many Phantoms are returned?

/agents/fetch-all returns all Phantoms in your Workspace. /orgs/export-agent-usage covers up to 6 months of usage data.

Can I use the Agent IDs from these endpoints in other API calls?

Yes. The Agent IDs returned can be reused in any endpoint that requires one, such as launching, updating, or retrieving results from a Phantom.