Trigger an Agent via API
Call your Squadbase Agents on demand from external workflows in addition to scheduled runs
When you create an Agent, it runs automatically on the schedule you set. In addition to that, you can start the same agent on demand via the Squadbase API — so an external system can run it exactly when it's needed instead of waiting for the next scheduled run.
When to use this
Triggering via API lets you wire your Agents into external workflow and automation tools — Zapier, n8n, Make, cron jobs, internal tools, CI pipelines, chatbots, and more.
A common pattern is automated reporting: an external workflow detects an event (a deal closes, a form is submitted, a build finishes) and calls the agent to analyze the latest data and deliver a report to email, Slack, or Microsoft Teams — no manual step in between.
Example use cases
- Event-driven reports — when a Zapier/n8n workflow fires (e.g. a new row in a sheet, a webhook from your product), trigger an agent to compile and send the relevant report.
- Cross-tool orchestration — make a Squadbase Agent one step in a larger automation pipeline, passing its result downstream.
- Ad-hoc runs from your own tools — add a "Generate report" button to an internal app that calls the agent directly.
How it works
The agent you already built — its data sources, instructions, and notification settings — runs exactly as configured. The only difference is what starts it: instead of the schedule, your API call does.
To trigger an agent you need two things:
- An API key — create one from your Squadbase account settings. See API Key Authentication.
- The Agent ID of the agent you want to run.
You can also pass an optional message to give the agent an instruction for that specific run.
The trigger endpoint is asynchronous: the API responds as soon as the run starts (status: RUNNING), and the agent delivers its result to the configured notification channels when it finishes.
curl -X POST 'https://api.squadbase.dev/v0/agent/<AGENT_ID>/trigger' \
-H 'x-api-key: <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{"message":"Analyze this week'\''s signup trends","title":"Weekly analysis"}'The response includes an executionId. Besides the notification channels, you can use it to poll the execution status and fetch the result programmatically.
If your automation tool retries failed requests, send an Idempotency-Key header so a retry doesn't start a duplicate run — the same key returns the original execution. It's optional; when omitted, each request starts a new run. See Trigger an Agent.
For the full specification — request body, status and result endpoints, response shapes, and error codes, plus Python and Node.js examples — see the API Overview.