Flow Technical Notes

Configuration, limits, best practices, and implementation details

This page provides technical details, configuration options, limits, and best practices for working with flows.

Cron Expression Syntax

Time-based flows use cron expressions to define schedules. Cron expressions consist of 5 fields separated by spaces.

Cron Format

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *

Special Characters

*: Any value. Example: * * * * * runs every minute.
,: Value list separator. Example: 0 9,17 * * * runs at 9 AM and 5 PM.
-: Range of values. Example: 0 9-17 * * * runs every hour from 9 AM to 5 PM.
/: Step values. Example: */15 * * * * runs every 15 minutes.

Common Patterns

# Every minute
* * * * *
 
# Every hour at minute 0
0 * * * *
 
# Every day at midnight
0 0 * * *
 
# Every day at 9:30 AM
30 9 * * *
 
# Every Monday at 9 AM
0 9 * * 1
 
# Every weekday at 6 PM
0 18 * * 1-5
 
# Every 15 minutes
*/15 * * * *
 
# First day of every month at midnight
0 0 1 * *
 
# Last day of every month (not directly supported, use day 28-31 with logic)
0 0 28-31 * *
 
# Every quarter (Jan, Apr, Jul, Oct) on the 1st at midnight
0 0 1 1,4,7,10 *

Validation

Cron expressions are validated on flow creation. Invalid expressions return a validation error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid cron expression: Expected 5 fields, got 4",
    "details": {
      "field": "schedule",
      "cronExpression": "0 9 * *"
    }
  }
}

Common validation errors:

Incorrect number of fields (must be exactly 5)
Values out of range (e.g., hour = 25)
Invalid step values (e.g., */0)
Malformed expressions

Timezone Handling

All cron schedules execute in UTC timezone. To schedule for a specific local timezone, calculate the UTC offset:

# 9 AM Pacific Time (UTC-8) = 5 PM UTC
0 17 * * *
 
# 9 AM Eastern Time (UTC-5) = 2 PM UTC
0 14 * * *
 
# During daylight saving time, adjust accordingly

Tip: Use tools like crontab.guru to validate and understand cron expressions.

Event Condition Syntax

Event-based flows use condition trees to filter events. Conditions support nested AND/OR logic with field-level comparisons.

Condition Structure

{
  "operator": "AND",
  "conditions": [
    {
      "field": "text",
      "operator": "contains",
      "value": "urgent"
    },
    {
      "field": "sender",
      "operator": "equals",
      "value": "john_doe"
    }
  ]
}

Operators

Logical Operators

AND: All nested conditions must be true.
OR: At least one nested condition must be true.

Comparison Operators

equals: Field value exactly matches the specified value.
contains: Field value contains the specified substring (case-insensitive).
startsWith: Field value starts with the specified prefix.
endsWith: Field value ends with the specified suffix.
greaterThan: Field value is greater than the specified number.
lessThan: Field value is less than the specified number.
exists: Field is present in the event (value should be true/false).
regex: Field value matches the specified regular expression.

Nested Conditions

Conditions can be nested to create complex logic:

{
  "operator": "AND",
  "conditions": [
    {
      "operator": "OR",
      "conditions": [
        {
          "field": "text",
          "operator": "contains",
          "value": "urgent"
        },
        {
          "field": "text",
          "operator": "contains",
          "value": "asap"
        }
      ]
    },
    {
      "field": "isGroupChat",
      "operator": "equals",
      "value": false
    }
  ]
}

This matches: (text contains "urgent" OR text contains "asap") AND (not a group chat)

Available Fields by Event Type

Different event types provide different fields for filtering:

telegram.message:

text - Message text content
sender - Username of message sender
chatId - Telegram chat ID
isGroupChat - Boolean indicating group chat
timestamp - Message timestamp

gmail.email_received:

subject - Email subject line
from - Sender email address
to - Recipient email addresses
body - Email body content
hasAttachment - Boolean indicating attachments
timestamp - Email received timestamp

calendar.event_created:

summary - Event title
description - Event description
location - Event location
attendees - Array of attendee emails
startTime - Event start timestamp
endTime - Event end timestamp

voice.call_ended:

duration - Call duration in seconds
participants - Array of participant IDs
summary - AI-generated call summary
transcript - Call transcript
timestamp - Call end timestamp

Execution Modes

LLM Mode

Characteristics:

Executes natural language prompts via AI agent
Automatically selects and uses appropriate tools
Handles multi-step workflows intelligently
Adapts to context and edge cases
Higher latency (~2-10 seconds)
Variable cost based on prompt complexity

Best For:

Complex decision-making workflows
Natural language processing tasks
Dynamic tool selection requirements
Rapid prototyping and iteration

Configuration:

{
  "scriptId": "script_abc123"
}

All flows now execute scripts directly for deterministic, predictable behavior with lower latency and fixed costs.

Limits and Quotas

Flow Creation Limits

Maximum flows per user: 1,000
Maximum flows created per day: 100
Maximum flow title length: 200 characters
Maximum flow description length: 1,000 characters
Maximum prompt length: 10,000 characters

Execution Limits

Maximum executions per flow per day: 10,000
Maximum concurrent executions per flow: 10
Maximum execution duration: 300 seconds (5 minutes)
Maximum memory per execution: 3,008 MB

Cron Schedule Limits

Minimum interval between executions: 1 minute
Maximum schedules per flow: 1
Timezone: UTC only

Event Condition Limits

Maximum condition tree depth: 5 levels
Maximum conditions per tree: 50
Maximum field name length: 100 characters
Maximum condition value length: 1,000 characters

Recommended Limits

For optimal performance and cost control, we recommend:

Cron frequency: No more frequent than every 5 minutes for most use cases
Event conditions: Keep condition trees simple (≤3 levels deep)
Execution duration: Target ≤30 seconds for LLM mode, ≤10 seconds for direct mode
Tool recommendations: Specify 2-5 tools maximum

Performance Optimization

Cron Schedule Optimization

Distribute load across time:

# ❌ Bad: All flows execute at midnight
0 0 * * *
 
# ✅ Good: Distribute across the hour
13 0 * * *  # 00:13
27 0 * * *  # 00:27
45 0 * * *  # 00:45

Use appropriate intervals:

# ❌ Bad: Every minute for non-critical tasks
* * * * *
 
# ✅ Good: Appropriate interval
*/15 * * * *  # Every 15 minutes

Event Condition Optimization

Use specific conditions early:

{
  "operator": "AND",
  "conditions": [
    {
      "field": "sender",
      "operator": "equals",
      "value": "specific_user"
    },
    {
      "field": "text",
      "operator": "contains",
      "value": "keyword"
    }
  ]
}

This is more efficient than:

{
  "operator": "AND",
  "conditions": [
    {
      "field": "text",
      "operator": "regex",
      "value": ".*complex.*pattern.*"
    },
    {
      "field": "sender",
      "operator": "equals",
      "value": "specific_user"
    }
  ]
}

Avoid expensive operations:

Minimize regex conditions (use simple string operations when possible)
Place specific filters before general filters
Use equals instead of contains when exact match is needed

Execution Optimization

Keep prompts focused:

{
  "prompt": "1) Check Bitcoin price via resources, 2) If above $50k, send Telegram alert"
}

vs.

{
  "prompt": "Analyze all cryptocurrency markets, generate comprehensive report with charts, email to 10 recipients, save to multiple locations, and post updates to social media"
}

Use direct mode for deterministic tasks:

{
  "scriptId": "optimized_script_123"
}

Error Handling

Execution Errors

Flows automatically retry failed executions with exponential backoff:

1st retry: After 1 minute
2nd retry: After 5 minutes
3rd retry: After 15 minutes
Final retry: After 1 hour

After 4 failed attempts, the flow is paused and you receive a notification.

Validation Errors

Validation errors occur during flow creation or update:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid cron expression: Expected 5 fields, got 4",
    "details": {
      "field": "schedule",
      "value": "0 9 * *"
    }
  }
}

Common causes:

Invalid cron expression syntax
Missing required fields
Invalid event type
Malformed condition tree
Field values exceeding limits

Runtime Errors

Runtime errors occur during flow execution:

{
  "executionId": "exec_123",
  "status": "failed",
  "error": {
    "code": "TIMEOUT",
    "message": "Execution exceeded maximum duration of 300 seconds"
  }
}

Common causes:

Execution timeout (exceeded 300 seconds)
Memory limit exceeded
Cost limit exceeded
Tool/resource unavailable
Invalid tool parameters

Security and Privacy

Access Control

Flows execute with the creating user's permissions:

Access user's Telegram messages
Access user's Gmail
Access user's calendar events
Use user's API keys and resources

Flows cannot:

Access other users' data
Execute with elevated privileges
Bypass resource access controls
Modify other users' flows

Data Retention

Flow execution data is retained:

Execution history: Last 100 executions
Execution logs: 30 days
Execution results: 90 days

API Key Security

Flow API operations require authentication via API key:

curl -X POST https://api.getmirra.app/api/sdk/v1/flows/createTimeFlow \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Best practices:

Rotate API keys regularly
Use environment variables for API keys
Never commit API keys to version control
Revoke compromised keys immediately

Cost Management

Understanding Costs

Flow execution costs include:

Scheduling overhead: Minimal (~$0.0001 per scheduled check)
LLM execution: $0.01 - $0.10 per execution (varies by complexity)
Direct execution: $0.001 - $0.01 per execution (varies by script)
Tool usage: Variable based on external API costs

Estimating Costs

Example 1: Daily report flow

Schedule: Daily (365 executions/year)
Execution type: LLM
Average cost per execution: $0.05
Annual cost: 365 * $0.05 = $18.25

Example 2: High-frequency monitoring

Schedule: Every 5 minutes (105,120 executions/year)
Execution type: Direct
Average cost per execution: $0.001
Annual cost: 105,120 * $0.001 = $105.12

Cost Optimization

Use appropriate execution modes:

LLM mode: Complex, variable tasks
Direct mode: Simple, deterministic tasks

Optimize schedules:

Reduce frequency when possible
Combine multiple checks into single execution
Use event-based triggers instead of polling

Set budget limits:

{
  "config": {
    "maxCostPerExecution": 0.10,
    "maxExecutionsPerDay": 100
  }
}

Monitoring and Observability

Execution History

View detailed execution history:

curl -X POST https://api.getmirra.app/api/sdk/v1/flows/getFlow \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"assignmentId": "flow_123"}'

Response includes:

{
  "executionCount": 145,
  "executionResults": [
    {
      "executionId": "exec_789",
      "timestamp": "2025-12-06T09:00:00Z",
      "status": "success",
      "duration": 2341,
      "cost": 0.023,
      "logs": ["Step 1 complete", "Step 2 complete"],
      "result": {"success": true, "data": {...}}
    }
  ],
  "lastExecutedAt": "2025-12-06T09:00:00Z"
}

Metrics and Analytics

Track flow performance:

Execution count: Total number of executions
Success rate: Percentage of successful executions
Average duration: Mean execution time
Average cost: Mean cost per execution
Last execution: Most recent execution timestamp

Debugging Failed Executions

For failed executions, review:

Error message: Primary error description
Execution logs: Step-by-step execution trace
Stack trace: Detailed error context (for script executions)
Input data: Event or trigger data that caused execution

Best Practices

Design Principles

Single Responsibility:

Each flow should do one thing well
Break complex workflows into multiple flows
Chain flows via events or schedules when needed

Idempotency:

Design flows to be safely re-executable
Handle duplicate executions gracefully
Use unique identifiers to prevent duplicates

Fault Tolerance:

Expect and handle errors gracefully
Use try-catch patterns in prompts
Implement fallback behaviors

Testing

Test in draft mode:

Create flow
Test with manual trigger
Verify results
Activate schedule/events

Gradual rollout:

Start with infrequent schedules
Monitor initial executions
Increase frequency after verification

Error notification:

Set up alerts for failed executions
Review error logs regularly
Fix issues proactively

Documentation

Document your flows:

{
  "title": "Clear, Descriptive Title",
  "description": "Detailed description including: what it does, when it runs, what tools it uses, expected outcomes, and any dependencies"
}

Version control:

Track flow configuration changes
Document significant updates
Maintain changelog for complex flows

Troubleshooting

Flow Not Executing

Check:

Flow status is "active" not "paused"
Cron expression is valid and in UTC
Daily execution limit not exceeded
User has required tool permissions

Execution Failures

Check:

Execution logs for error messages
Tool availability and credentials
Resource access permissions
Execution duration and memory limits

Unexpected Behavior

Check:

Event condition logic (AND vs OR)
Field names match event schema
Timezone calculations for cron
Prompt clarity and tool recommendations

Flow Technical Notes

On this page