Reference

Best Practices

  1. Start simple: Test actions with 1-2 steps before adding complexity
  2. Use webhooks for long actions: Anything over 30 seconds should use async execution
  3. Set appropriate token limits: Prevent runaway costs with max_tokens
  4. Store results: Use Vault steps to persist important outputs
  5. Handle errors gracefully: Actions stop on first error - design accordingly
  6. Test variable interpolation: Verify {{variables}} resolve correctly before production
  7. Monitor execution history: Check /executions/{id} for debugging

Pricing

Actions are billed based on the services used:

  • Templates: Based on LLM usage (input/output tokens)
  • LLM: Model-specific token pricing
  • OCR: Per page processed
  • Vault: Storage and API calls
  • Voice: Per minute transcribed

Total cost is the sum of all step costs, shown in the execution response.

Error Handling

Action Fails

If any step fails, the action stops and returns an error:

{
  "execution_id": "exec_xyz",
  "status": "failed",
  "error": "Step 'ocr_document' failed: Document not found",
  "currentStep": 0,
  "totalSteps": 3
}

Webhook Failure

If webhook delivery fails, we retry 3 times with exponential backoff. Check delivery history:

GET /webhooks/v1/{webhook_id}/deliveries

Limits

  • Max steps per action: 20 steps
  • Max execution time: 5 minutes (use webhooks for longer)
  • Max input size: 10MB
  • Webhook timeout: 30 seconds
  • Webhook retries: 3 attempts

Security

  • ✅ Actions scoped to organization: Only access your own actions
  • ✅ Webhook signature verification: HMAC SHA-256 prevents spoofing
  • ✅ HTTPS required for webhooks: No insecure endpoints
  • ✅ API key authentication: Required for all operations
  • ✅ Audit trail: All executions logged with full history

Related

Managing Actions
Variable Interpolation