Triggers let you schedule browser automation tasks that execute automatically on a recurring basis. Each trigger is tied to an environment , so it inherits the browser profile, stored cookies, and persistent files — no re-authentication required between runs.
Why Triggers Without triggers With triggers You trigger every task manually via API call Tasks run automatically on your chosen schedule You build and maintain your own scheduler Scheduling, retries, and failure handling are built in Missed runs require manual intervention The system tracks run history and pauses after repeated failures Webhook delivery requires custom wiring per task Delivery mode (webhook, bot, or both) is configured once per trigger
How It Works
Create a trigger linked to an environment, with a schedule and task details.The system executes your task at each scheduled time using the environment’s browser profile and files.Results are delivered via webhook, bot notification, or both — depending on your deliveryMode setting.Run history is recorded for every execution so you can audit outcomes and debug failures.
Create trigger → System runs on schedule → Results delivered → Run history logged
Schedule Types Every trigger requires a scheduleType that determines when and how often it runs.
Type Field Description Example atscheduleAtRun once at a specific date/time (ISO 8601) "2026-03-01T09:00:00Z"everyscheduleIntervalRun at a fixed interval "30m", "2h", "1d"cronscheduleCronStandard cron expression for full scheduling control "0 9 * * 1-5" (weekdays at 9 AM)
All schedules respect the timezone field (defaults to UTC).
Use scheduleType: "cron" with a standard cron expression for maximum flexibility — for example, "0 */6 * * *" runs every 6 hours, and "30 8 1 * *" runs at 8:30 AM on the first of each month.
Delivery Modes Control how run results are delivered using the deliveryMode field.
Mode Description webhookResults are sent to your configured webhook endpoint botResults are delivered via bot notification bothResults are sent to both webhook and bot
When deliveryMode is webhook or both, you must provide a webhook configuration object. See Webhooks for details on webhook parameters.
Automation Policy Triggers can optionally be associated with an automation policy . Policies define rules that govern agent behavior during execution — such as domain restrictions, blocked keywords, action type controls, and capability limits.
When a policy is assigned, the browser agent will enforce those rules for every run of the trigger. This is useful for compliance, safety guardrails, or scoping what the agent is allowed to do.
To assign a policy, pass the policyId field when creating or updating a trigger, or select one from the “Automation Policy” dropdown in the dashboard.
Trigger Statuses Status Meaning activeTrigger is running on schedule pausedTrigger is paused and will not execute until resumed
A trigger is automatically paused after reaching maxConsecutiveFailures (default: 5). Resume it with the resume endpoint after resolving the issue.
Authentication All endpoints require an API key in the Authorization header:
Authorization: Bearer < api_ke y >
Base URL https://connect.webrun.ai
List Triggers Returns all triggers for the authenticated user, sorted by creation date (newest first).
curl https://connect.webrun.ai/cron-jobs \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "cronJobs" : [ { "_id" : "664a1b2c3d4e5f6a7b8c9d0e" , "userId" : "67f1a2b3c4d5e6f7a8b9c0d1" , "environmentId" : "683a1f2e4b0c1d2e3f4a5b6c" , "policyId" : null , "name" : "Daily price check" , "description" : "Check competitor prices every morning" , "scheduleType" : "cron" , "scheduleCron" : "0 9 * * *" , "timezone" : "America/New_York" , "taskDetails" : "Go to competitor.com/pricing and extract all plan prices" , "outputType" : "structured" , "deliveryMode" : "webhook" , "status" : "active" , "nextRunAt" : "2026-02-25T14:00:00.000Z" , "consecutiveFailures" : 0 , "createdAt" : "2026-02-20T10:00:00.000Z" } ] }
Create a Trigger POST /cron-jobs Content-Type: application/json
Request Body Field Type Required Description namestring Yes Trigger name descriptionstring No Optional description environmentIdstring Yes ID of the environment to use scheduleTypestring Yes "at", "every", or "cron"scheduleAtstring Conditional ISO 8601 datetime (required when scheduleType is "at") scheduleIntervalstring Conditional Interval string like "30m", "2h" (required when scheduleType is "every") scheduleCronstring Conditional Cron expression (required when scheduleType is "cron") timezonestring No IANA timezone (default: "UTC") taskDetailsstring Yes Instructions for the browser automation task startingUrlstring No URL where the task should begin outputTypestring No "text" (default) or "structured"outputSchemaobject No JSON Schema for structured output (when outputType is "structured") deliveryModestring No "webhook", "bot", or "both" (default: "webhook")webhookobject Conditional Webhook config (required when deliveryMode includes "webhook") retryPolicyobject No Custom retry configuration policyIdstring No ID of an automation policy to apply to this trigger’s executions. When set, the browser agent will follow the policy’s rules (domain restrictions, keyword blocking, capability controls, etc.) maxConsecutiveFailuresnumber No Failures before auto-pause (default: 5)
Example: Recurring Cron Schedule curl -X POST https://connect.webrun.ai/cron-jobs \ -H "Authorization: Bearer enig_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Daily price check", "description": "Check competitor prices every morning", "environmentId": "<ENV_ID>", "policyId": "665a1f...abc", "scheduleType": "cron", "scheduleCron": "0 9 * * 1-5", "timezone": "America/New_York", "taskDetails": "Go to competitor.com/pricing and extract all plan prices", "startingUrl": "https://competitor.com/pricing", "outputType": "structured", "outputSchema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "number" } } } } } }, "deliveryMode": "webhook", "webhook": { "name": "Price Updates", "url": "https://api.yoursite.com/webhooks/prices", "auth": "Bearer your-secret-token", "submittedData": "ai_response" } }'
Example: Fixed Interval curl -X POST https://connect.webrun.ai/cron-jobs \ -H "Authorization: Bearer enig_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Inventory monitor", "environmentId": "<ENV_ID>", "policyId": null, "scheduleType": "every", "scheduleInterval": "2h", "taskDetails": "Check the inventory page and report any out-of-stock items", "startingUrl": "https://store.example.com/inventory", "deliveryMode": "webhook", "webhook": { "name": "Inventory Alert", "url": "https://api.yoursite.com/webhooks/inventory", "submittedData": "ai_response" } }'
Example: One-Time Scheduled Run curl -X POST https://connect.webrun.ai/cron-jobs \ -H "Authorization: Bearer enig_xxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Q1 report export", "environmentId": "<ENV_ID>", "scheduleType": "at", "scheduleAt": "2026-04-01T06:00:00Z", "taskDetails": "Log into the dashboard and export the Q1 revenue report as PDF", "deliveryMode": "bot" }'
Response (201 Created): { "success" : true , "cronJob" : { "_id" : "664a1b2c3d4e5f6a7b8c9d0e" , "name" : "Daily price check" , "environmentId" : "683a1f2e4b0c1d2e3f4a5b6c" , "policyId" : "665a1f...abc" , "scheduleType" : "cron" , "scheduleCron" : "0 9 * * 1-5" , "timezone" : "America/New_York" , "taskDetails" : "Go to competitor.com/pricing and extract all plan prices" , "status" : "active" , "nextRunAt" : "2026-02-25T14:00:00.000Z" , "createdAt" : "2026-02-24T10:00:00.000Z" } }
Errors Status Message Cause 400 name is required Missing or empty name 400 taskDetails is required Missing or empty taskDetails 400 Valid environmentId is required Missing or invalid environment ID 400 Maximum of N cron jobs per user User limit reached 400 webhook config is required when deliveryMode includes webhook Missing webhook config 404 Environment not found Environment does not exist or belongs to another user
Get a Trigger Returns a single trigger with its 10 most recent runs.
curl https://connect.webrun.ai/cron-jobs/ < JOB_I D > \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "cronJob" : { "_id" : "664a1b2c3d4e5f6a7b8c9d0e" , "name" : "Daily price check" , "status" : "active" , "nextRunAt" : "2026-02-25T14:00:00.000Z" , "consecutiveFailures" : 0 }, "recentRuns" : [ { "_id" : "run_abc123" , "cronJobId" : "664a1b2c3d4e5f6a7b8c9d0e" , "status" : "completed" , "createdAt" : "2026-02-24T14:00:00.000Z" } ] }
Errors Status Message Cause 404 Cron job not found Invalid ID or job belongs to another user
Update a Trigger Update any field on an existing trigger. Only include the fields you want to change.
PUT /cron-jobs/:id Content-Type: application/json
curl -X PUT https://connect.webrun.ai/cron-jobs/ < JOB_I D > \ -H "Authorization: Bearer enig_xxx" \ -H "Content-Type: application/json" \ -d '{ "scheduleCron": "0 8 * * 1-5", "timezone": "Europe/London" }'
Response: { "success" : true , "cronJob" : { "_id" : "664a1b2c3d4e5f6a7b8c9d0e" , "name" : "Daily price check" , "scheduleCron" : "0 8 * * 1-5" , "timezone" : "Europe/London" , "nextRunAt" : "2026-02-25T08:00:00.000Z" } }
Changing schedule-related fields (scheduleType, scheduleAt, scheduleInterval, scheduleCron, timezone) automatically recomputes nextRunAt.
Errors Status Message Cause 404 Cron job not found Invalid ID or job belongs to another user
Delete a Trigger Permanently deletes a trigger and all its run history.
curl -X DELETE https://connect.webrun.ai/cron-jobs/ < JOB_I D > \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "message" : "Cron job deleted" }
Errors Status Message Cause 404 Cron job not found Invalid ID or job belongs to another user
Pause a Trigger Pause an active trigger. The trigger will stop executing until resumed.
POST /cron-jobs/:id/pause
curl -X POST https://connect.webrun.ai/cron-jobs/ < JOB_I D > /pause \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "cronJob" : { "_id" : "664a1b2c3d4e5f6a7b8c9d0e" , "status" : "paused" } }
Errors Status Message Cause 400 Cannot pause a job with status “paused” Job is not currently active 404 Cron job not found Invalid ID or job belongs to another user
Resume a Trigger Resume a paused trigger. Resets the consecutive failure counter and recomputes the next run time.
POST /cron-jobs/:id/resume
curl -X POST https://connect.webrun.ai/cron-jobs/ < JOB_I D > /resume \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "cronJob" : { "_id" : "664a1b2c3d4e5f6a7b8c9d0e" , "status" : "active" , "consecutiveFailures" : 0 , "nextRunAt" : "2026-02-25T14:00:00.000Z" } }
Errors Status Message Cause 400 Cannot resume a job with status “active” Job is not currently paused 404 Cron job not found Invalid ID or job belongs to another user
Run a Trigger Manually Immediately run a trigger outside of its normal schedule. The run executes in the background.
POST /cron-jobs/:id/trigger
curl -X POST https://connect.webrun.ai/cron-jobs/ < JOB_I D > /trigger \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "message" : "Job triggered. Check runs endpoint for results." }
Manual triggers run independently of the trigger’s schedule. The trigger’s nextRunAt is not affected.
Errors Status Message Cause 404 Cron job not found Invalid ID or job belongs to another user
List Trigger Runs Returns paginated execution history for a trigger.
Parameter Location Default Description pageQuery 1Page number limitQuery 20Results per page (max 50)
curl "https://connect.webrun.ai/cron-jobs/<JOB_ID>/runs?page=1&limit=10" \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "runs" : [ { "_id" : "run_abc123" , "cronJobId" : "664a1b2c3d4e5f6a7b8c9d0e" , "status" : "completed" , "createdAt" : "2026-02-24T14:00:00.000Z" } ], "pagination" : { "page" : 1 , "limit" : 10 , "total" : 45 , "totalPages" : 5 } }
Get a Specific Run Returns details for a single run.
GET /cron-jobs/:id/runs/:runId
curl https://connect.webrun.ai/cron-jobs/ < JOB_I D > /runs/ < RUN_I D > \ -H "Authorization: Bearer enig_xxx"
Response: { "success" : true , "run" : { "_id" : "run_abc123" , "cronJobId" : "664a1b2c3d4e5f6a7b8c9d0e" , "status" : "completed" , "createdAt" : "2026-02-24T14:00:00.000Z" } }
Errors Status Message Cause 404 Cron job not found Invalid job ID or job belongs to another user 404 Run not found Invalid run ID or run does not belong to this job
Common Errors All error responses follow this format:
{ "success" : false , "message" : "Description of the error" }
Status Message Cause 401 API key required Missing Authorization header 401 Invalid or revoked API key API key is incorrect or has been revoked 403 Account is deactivated User account is disabled 500 Server error Unexpected server-side failure
