Triggers API - Eliza

Triggers schedule the agent to perform tasks automatically. They are backed by the elizaOS TaskService and support interval-based, cron-based, and one-shot scheduling. The agent must be running and triggers must be enabled in configuration.

<Info> Triggers are disabled by configuration in some deployments. Check `GET /api/triggers/health` to verify the trigger system is available. </Info>

Endpoints

GET /api/triggers/health

Get the trigger system health snapshot. This endpoint works even when triggers are disabled.

Response

json

{
  "triggersEnabled": true,
  "activeTriggers": 3,
  "disabledTriggers": 1,
  "totalExecutions": 42,
  "totalFailures": 2,
  "totalSkipped": 0
}

GET /api/triggers

List all triggers, sorted alphabetically by display name.

Response

json

{
  "triggers": [
    {
      "triggerId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Morning Check-in",
      "triggerType": "interval",
      "enabled": true,
      "intervalMs": 3600000,
      "instructions": "Post a morning update",
      "wakeMode": "inject_now",
      "createdBy": "api",
      "nextRunAtMs": 1718003600000,
      "lastRunAtMs": 1718000000000,
      "runCount": 5
    }
  ]
}

POST /api/triggers

Create a new trigger. Returns 429 if the active trigger limit for the creator is reached, and 409 if an equivalent trigger (same dedupe key) already exists.

Request

json

{
  "displayName": "Morning Check-in",
  "instructions": "Post a morning update about what you're working on",
  "triggerType": "interval",
  "intervalMs": 3600000,
  "wakeMode": "inject_now",
  "enabled": true,
  "createdBy": "api"
}

Parameter	Type	Required	Description
`kind`	string	No	Trigger kind: `"text"` (default) or `"workflow"`. Workflow triggers require `workflowId`.
`displayName`	string	No	Human-readable trigger name (default: `"New Trigger"`)
`instructions`	string	No	Instructions for the agent when this trigger fires
`triggerType`	string	No	`"interval"`, `"cron"`, or `"once"` (default: `"interval"`)
`intervalMs`	number	No	Interval in milliseconds (for `triggerType: "interval"`)
`cronExpression`	string	No	Cron expression (for `triggerType: "cron"`)
`scheduledAtIso`	string	No	ISO 8601 datetime for one-shot triggers (for `triggerType: "once"`)
`maxRuns`	number	No	Maximum number of times this trigger can fire
`wakeMode`	string	No	`"inject_now"` fires immediately (default), other modes defer
`enabled`	boolean	No	Whether the trigger is active (default: `true`)
`createdBy`	string	No	Creator identifier for limit tracking (default: `"api"`)
`workflowId`	string	No	workflow ID (required when `kind` is `"workflow"`)
`workflowName`	string	No	Human-readable workflow name (for `kind: "workflow"`)

Response (201 Created)

json

{
  "trigger": {
    "triggerId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Morning Check-in",
    "triggerType": "interval",
    "enabled": true,
    "intervalMs": 3600000,
    "nextRunAtMs": 1718003600000
  }
}

GET /api/triggers/:id

Get a trigger by its ID (trigger UUID or task UUID).

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Trigger ID or task ID

Response

json

{
  "trigger": {
    "triggerId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Morning Check-in",
    "triggerType": "interval",
    "enabled": true,
    "intervalMs": 3600000
  }
}

PUT /api/triggers/:id

Update a trigger. Fields not provided are preserved from the existing trigger. Changing schedule parameters recomputes nextRunAtMs.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Trigger ID

Request

json

{
  "displayName": "Updated Morning Check-in",
  "intervalMs": 7200000,
  "enabled": true
}

Parameter	Type	Required	Description
`displayName`	string	No	New display name
`instructions`	string	No	New instructions
`intervalMs`	number	No	New interval in milliseconds
`cronExpression`	string	No	New cron expression
`scheduledAtIso`	string	No	New one-shot datetime
`maxRuns`	number	No	New maximum run count
`enabled`	boolean	No	Enable or disable the trigger

Response

json

{
  "trigger": {
    "triggerId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Updated Morning Check-in",
    "enabled": true,
    "intervalMs": 7200000,
    "nextRunAtMs": 1718007200000
  }
}

DELETE /api/triggers/:id

Delete a trigger permanently.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Trigger ID

Response

json

{
  "ok": true
}

POST /api/triggers/:id/execute

Manually execute a trigger immediately, regardless of its schedule.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Trigger ID

Response

json

{
  "ok": true,
  "result": { "success": true },
  "trigger": {
    "triggerId": "550e8400-e29b-41d4-a716-446655440000",
    "runCount": 6,
    "lastRunAtMs": 1718001000000
  }
}

GET /api/triggers/:id/runs

Get the run history for a trigger.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Trigger ID

Response

json

{
  "runs": [
    {
      "runId": "run-001",
      "startedAt": 1718000000000,
      "completedAt": 1718000005000,
      "success": true,
      "source": "scheduled"
    }
  ]
}

Common Error Codes

Status	Code	Description
400	`INVALID_REQUEST`	Request body is malformed or missing required fields
401	`UNAUTHORIZED`	Missing or invalid authentication token
404	`NOT_FOUND`	Requested resource does not exist
409	`TRIGGER_EXISTS`	A trigger with the same configuration already exists
429	`TRIGGER_LIMIT_REACHED`	Maximum number of triggers for this creator has been reached
500	`TRIGGER_DISABLED`	Trigger system is disabled in configuration
500	`INTERNAL_ERROR`	Unexpected server error