Skip to main content
Once you’ve built and published a tool, there are several ways to execute it. Choose the method that best fits your use case. Triggering a tool

​
Trigger tab

The most direct way to trigger a tool is through the Trigger tab in the Cargo interface.

​
Single run

Execute a tool once with specific parameters:
  1. Navigate to your tool in the Cargo workspace
  2. Click on the Trigger tab
  3. Select Single mode
  4. Enter the required input parameters
  5. Click Run tool to execute immediately
Single runs are perfect for testing tools or processing one-off requests without setting up a full workflow.

​
Bulk run

Process multiple records at once:
  1. Navigate to your tool and select the Trigger tab
  2. Choose Bulk mode
  3. Upload a CSV file containing multiple input records
  4. Map the CSV columns to your tool’s input fields
  5. Click Continue to process the entire batch
Your CSV should have headers that match your tool’s input field names. For example: 
company_domain,contact_email
acme.com,john@acme.com
globex.io,jane@globex.io

​
Through a play

Integrate tools into automated workflows by adding them as actions in a play.
  1. Create or edit a play
  2. Add your tool as a node in the play
  3. Map inputs from previous play nodes or enrolled data
  4. Configure what happens with the tool’s output
The tool executes automatically when the play runs, and its results can be passed to subsequent actions. This is ideal for building multi-step automation sequences.

Learn more about plays

See how to build plays that orchestrate multiple tools together.

​
Through an agent

AI agents can autonomously decide when and how to use your tools.
  1. Open your agent’s configuration
  2. Add your tool to the agent’s available tools
  3. The agent will automatically trigger the tool when relevant to the conversation
Tool results feed into the agent’s reasoning process, enabling sophisticated workflows where the agent chains multiple tools together based on context.

Configure agent tools

Learn how to give agents access to your tools.

​
Through an MCP server

Model Context Protocol (MCP) allows external AI systems to discover and use your tools.
  1. Enable MCP server in your Cargo workspace settings
  2. Configure which tools are exposed via MCP
  3. Connect your MCP client (Claude Desktop, VS Code, etc.)
  4. Your tools appear as available actions in the external system
This is powerful for integrating Cargo tools with AI assistants and development environments.

​
Through API calls

Execute tools programmatically via the REST API for maximum flexibility and integration options.

​
Getting your API credentials

  1. Navigate to Settings → API in your Cargo workspace
  2. Generate or copy your API token
  3. Find your tool’s ID in the tool editor URL or settings

​
Execute endpoint

Execute a tool synchronously. If execution exceeds 5 minutes, it will time out. 
POST https://api.getcargo.io/v1/tools/{tool_id}/execute

​
Example request

curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/execute?token={your_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_domain": "acme.com",
    "contact_email": "john@acme.com"
  }'

​
Example response

{
  "status": "success",
  "createdAt": "2024-01-15T10:30:00Z",
  "finishedAt": "2024-01-15T10:30:02Z",
  "input": {
    "company_domain": "acme.com",
    "contact_email": "john@acme.com"
  },
  "output": {
    "company_name": "Acme Corporation",
    "employee_count": 500,
    "industry": "Technology"
  }
}

​
Batch execution

For processing multiple records or long-running operations, use the batch API.

​
Create a batch

curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/batches?token={your_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/cargo-callback",
    "data": [
      {"company_domain": "acme.com", "contact_email": "john@acme.com"},
      {"company_domain": "globex.io", "contact_email": "jane@globex.io"}
    ]
  }'
The webhookUrl field is optional. If provided, results will be sent to your webhook when the batch completes.

​
Batch creation response

{
  "batch": {
    "uuid": "batch_abc123",
    "status": "running"
  }
}

​
Retrieve batch results

Poll for results using the batch UUID: 
curl "https://api.getcargo.io/v1/tools/{tool_id}/batches/{batch_uuid}?token={your_token}"

​
Batch results response

{
  "batch": {
    "uuid": "batch_abc123",
    "status": "success"
  },
  "results": [
    {
      "status": "success",
      "createdAt": "2024-01-15T10:30:00Z",
      "finishedAt": "2024-01-15T10:30:02Z",
      "input": {
        "company_domain": "acme.com",
        "contact_email": "john@acme.com"
      },
      "output": {
        "company_name": "Acme Corporation",
        "employee_count": 500
      }
    }
  ]
}

​
Cancel a batch

Cancel an ongoing batch execution: 
curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/batches/{batch_uuid}/cancel?token={your_token}"

​
Choosing the right trigger method

MethodBest forAutomation level
Trigger tabTesting, ad-hoc execution, bulk importsManual
PlaysScheduled workflows, multi-step automationFully automated
AgentsContext-aware, intelligent automationAI-driven
MCP serverExternal AI system integrationAI-driven
APICustom applications, programmatic accessFully automated