External API

Sim provides a comprehensive external API for querying workflow execution logs and setting up webhooks for real-time notifications when workflows complete.

Authentication

All API requests require an API key passed in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" \
  https://sim.ai/api/v1/logs?workspaceId=YOUR_WORKSPACE_ID

You can generate API keys from your user settings in the Sim dashboard.

Logs API

All API responses include information about your workflow execution limits and usage:

"limits": {
  "workflowExecutionRateLimit": {
    "sync": {
      "requestsPerMinute": 60,  // Sustained rate limit per minute
      "maxBurst": 120,          // Maximum burst capacity
      "remaining": 118,         // Current tokens available (up to maxBurst)
      "resetAt": "..."          // When tokens next refill
    },
    "async": {
      "requestsPerMinute": 200, // Sustained rate limit per minute
      "maxBurst": 400,          // Maximum burst capacity
      "remaining": 398,         // Current tokens available
      "resetAt": "..."          // When tokens next refill
    }
  },
  "usage": {
    "currentPeriodCost": 1.234,  // Current billing period usage in USD
    "limit": 10,                  // Usage limit in USD
    "plan": "pro",                // Current subscription plan
    "isExceeded": false           // Whether limit is exceeded
  }
}

Note: Rate limits use a token bucket algorithm. remaining can exceed requestsPerMinute up to maxBurst when you haven't used your full allowance recently, allowing for burst traffic. The rate limits in the response body are for workflow executions. The rate limits for calling this API endpoint are in the response headers (X-RateLimit-*).

Query Logs

Query workflow execution logs with extensive filtering options.

GET /api/v1/logs

{
  "data": [
    {
      "id": "log_abc123",
      "workflowId": "wf_xyz789",
      "executionId": "exec_def456",
      "level": "info",
      "trigger": "api",
      "startedAt": "2025-01-01T12:34:56.789Z",
      "endedAt": "2025-01-01T12:34:57.123Z",
      "totalDurationMs": 334,
      "cost": {
        "total": 0.00234
      },
      "files": null
    }
  ],
  "nextCursor": "eyJzIjoiMjAyNS0wMS0wMVQxMjozNDo1Ni43ODlaIiwiaWQiOiJsb2dfYWJjMTIzIn0",
  "limits": {
    "workflowExecutionRateLimit": {
      "sync": {
        "requestsPerMinute": 60,
        "maxBurst": 120,
        "remaining": 118,
        "resetAt": "2025-01-01T12:35:56.789Z"
      },
      "async": {
        "requestsPerMinute": 200,
        "maxBurst": 400,
        "remaining": 398,
        "resetAt": "2025-01-01T12:35:56.789Z"
      }
    },
    "usage": {
      "currentPeriodCost": 1.234,
      "limit": 10,
      "plan": "pro",
      "isExceeded": false
    }
  }
}

Get Log Details

Retrieve detailed information about a specific log entry.

GET /api/v1/logs/{id}

{
  "data": {
    "id": "log_abc123",
    "workflowId": "wf_xyz789",
    "executionId": "exec_def456",
    "level": "info",
    "trigger": "api",
    "startedAt": "2025-01-01T12:34:56.789Z",
    "endedAt": "2025-01-01T12:34:57.123Z",
    "totalDurationMs": 334,
    "workflow": {
      "id": "wf_xyz789",
      "name": "My Workflow",
      "description": "Process customer data"
    },
    "executionData": {
      "traceSpans": [...],
      "finalOutput": {...}
    },
    "cost": {
      "total": 0.00234,
      "tokens": {
        "prompt": 123,
        "completion": 456,
        "total": 579
      },
      "models": {
        "gpt-4o": {
          "input": 0.001,
          "output": 0.00134,
          "total": 0.00234,
          "tokens": {
            "prompt": 123,
            "completion": 456,
            "total": 579
          }
        }
      }
    },
    "limits": {
      "workflowExecutionRateLimit": {
        "sync": {
          "requestsPerMinute": 60,
          "maxBurst": 120,
          "remaining": 118,
          "resetAt": "2025-01-01T12:35:56.789Z"
        },
        "async": {
          "requestsPerMinute": 200,
          "maxBurst": 400,
          "remaining": 398,
          "resetAt": "2025-01-01T12:35:56.789Z"
        }
      },
      "usage": {
        "currentPeriodCost": 1.234,
        "limit": 10,
        "plan": "pro",
        "isExceeded": false
      }
    }
  }
}

Get Execution Details

Retrieve execution details including the workflow state snapshot.

GET /api/v1/logs/executions/{executionId}

{
  "executionId": "exec_def456",
  "workflowId": "wf_xyz789",
  "workflowState": {
    "blocks": {...},
    "edges": [...],
    "loops": {...},
    "parallels": {...}
  },
  "executionMetadata": {
    "trigger": "api",
    "startedAt": "2025-01-01T12:34:56.789Z",
    "endedAt": "2025-01-01T12:34:57.123Z",
    "totalDurationMs": 334,
    "cost": {...}
  }
}

Notifications

Get real-time notifications when workflow executions complete via webhook, email, or Slack. Notifications are configured at the workspace level from the Logs page.

Configuration

Configure notifications from the Logs page by clicking the menu button and selecting "Configure Notifications".

Notification Channels:

• Webhook: Send HTTP POST requests to your endpoint
• Email: Receive email notifications with execution details
• Slack: Post messages to a Slack channel

Workflow Selection:

• Select specific workflows to monitor
• Or choose "All Workflows" to include current and future workflows

Filtering Options:

• levelFilter: Log levels to receive (info, error)
• triggerFilter: Trigger types to receive (api, webhook, schedule, manual, chat)

Optional Data:

• includeFinalOutput: Include the workflow's final output
• includeTraceSpans: Include detailed execution trace spans
• includeRateLimits: Include rate limit information (sync/async limits and remaining)
• includeUsageData: Include billing period usage and limits

Alert Rules

Instead of receiving notifications for every execution, configure alert rules to be notified only when issues are detected:

Consecutive Failures

• Alert after X consecutive failed executions (e.g., 3 failures in a row)
• Resets when an execution succeeds

Failure Rate

• Alert when failure rate exceeds X% over the last Y hours
• Requires minimum 5 executions in the window
• Only triggers after the full time window has elapsed

Latency Threshold

• Alert when any execution takes longer than X seconds
• Useful for catching slow or hanging workflows

Latency Spike

• Alert when execution is X% slower than the average
• Compares against the average duration over the configured time window
• Requires minimum 5 executions to establish baseline

Cost Threshold

• Alert when a single execution costs more than $X
• Useful for catching expensive LLM calls

No Activity

• Alert when no executions occur within X hours
• Useful for monitoring scheduled workflows that should run regularly

Error Count

• Alert when error count exceeds X within a time window
• Tracks total errors, not consecutive

All alert types include a 1-hour cooldown to prevent notification spam.

Webhook Configuration

For webhooks, additional options are available:

• url: Your webhook endpoint URL
• secret: Optional secret for HMAC signature verification

Payload Structure

When a workflow execution completes, Sim sends the following payload (via webhook POST, email, or Slack):

{
  "id": "evt_123",
  "type": "workflow.execution.completed",
  "timestamp": 1735925767890,
  "data": {
    "workflowId": "wf_xyz789",
    "executionId": "exec_def456",
    "status": "success",
    "level": "info",
    "trigger": "api",
    "startedAt": "2025-01-01T12:34:56.789Z",
    "endedAt": "2025-01-01T12:34:57.123Z",
    "totalDurationMs": 334,
    "cost": {
      "total": 0.00234,
      "tokens": {
        "prompt": 123,
        "completion": 456,
        "total": 579
      },
      "models": {
        "gpt-4o": {
          "input": 0.001,
          "output": 0.00134,
          "total": 0.00234,
          "tokens": {
            "prompt": 123,
            "completion": 456,
            "total": 579
          }
        }
      }
    },
    "files": null,
    "finalOutput": {...},  // Only if includeFinalOutput=true
    "traceSpans": [...],   // Only if includeTraceSpans=true
    "rateLimits": {...},   // Only if includeRateLimits=true
    "usage": {...}         // Only if includeUsageData=true
  },
  "links": {
    "log": "/v1/logs/log_abc123",
    "execution": "/v1/logs/executions/exec_def456"
  }
}

Webhook Headers

Each webhook request includes these headers (webhook channel only):

• sim-event: Event type (always workflow.execution.completed)
• sim-timestamp: Unix timestamp in milliseconds
• sim-delivery-id: Unique delivery ID for idempotency
• sim-signature: HMAC-SHA256 signature for verification (if secret configured)
• Idempotency-Key: Same as delivery ID for duplicate detection

Signature Verification

If you configure a webhook secret, verify the signature to ensure the webhook is from Sim:

import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const [timestampPart, signaturePart] = signature.split(',');
  const timestamp = timestampPart.replace('t=', '');
  const expectedSignature = signaturePart.replace('v1=', '');
  
  const signatureBase = `${timestamp}.${body}`;
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(signatureBase);
  const computedSignature = hmac.digest('hex');
  
  return computedSignature === expectedSignature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['sim-signature'];
  const body = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook...
});

import hmac
import hashlib
import json

def verify_webhook_signature(body: str, signature: str, secret: str) -> bool:
    timestamp_part, signature_part = signature.split(',')
    timestamp = timestamp_part.replace('t=', '')
    expected_signature = signature_part.replace('v1=', '')
    
    signature_base = f"{timestamp}.{body}"
    computed_signature = hmac.new(
        secret.encode(),
        signature_base.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(computed_signature, expected_signature)

# In your webhook handler
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('sim-signature')
    body = json.dumps(request.json)
    
    if not verify_webhook_signature(body, signature, os.environ['WEBHOOK_SECRET']):
        return 'Invalid signature', 401
    
    # Process the webhook...

Retry Policy

Failed webhook deliveries are retried with exponential backoff and jitter:

• Maximum attempts: 5
• Retry delays: 5 seconds, 15 seconds, 1 minute, 3 minutes, 10 minutes
• Jitter: Up to 10% additional delay to prevent thundering herd
• Only HTTP 5xx and 429 responses trigger retries
• Deliveries timeout after 30 seconds

Best Practices

1. Polling Strategy: When polling for logs, use cursor-based pagination with order=asc and startDate to fetch new logs efficiently.

2. Webhook Security: Always configure a webhook secret and verify signatures to ensure requests are from Sim.

3. Idempotency: Use the Idempotency-Key header to detect and handle duplicate webhook deliveries.

4. Privacy: By default, finalOutput and traceSpans are excluded from responses. Only enable these if you need the data and understand the privacy implications.

5. Rate Limiting: Implement exponential backoff when you receive 429 responses. Check the Retry-After header for the recommended wait time.

Rate Limiting

The API uses a token bucket algorithm for rate limiting, providing fair usage while allowing burst traffic:

How it works:

• Tokens refill at requestsPerMinute rate
• You can accumulate up to maxBurst tokens when idle
• Each request consumes 1 token
• Burst capacity allows handling traffic spikes

Rate limit information is included in response headers:

• X-RateLimit-Limit: Requests per minute (refill rate)
• X-RateLimit-Remaining: Current tokens available
• X-RateLimit-Reset: ISO timestamp when tokens next refill

Example: Polling for New Logs

let cursor = null;
const workspaceId = 'YOUR_WORKSPACE_ID';
const startDate = new Date().toISOString();

async function pollLogs() {
  const params = new URLSearchParams({
    workspaceId,
    startDate,
    order: 'asc',
    limit: '100'
  });
  
  if (cursor) {
    params.append('cursor', cursor);
  }
  
  const response = await fetch(
    `https://sim.ai/api/v1/logs?${params}`,
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );
  
  if (response.ok) {
    const data = await response.json();
    
    // Process new logs
    for (const log of data.data) {
      console.log(`New execution: ${log.executionId}`);
    }
    
    // Update cursor for next poll
    if (data.nextCursor) {
      cursor = data.nextCursor;
    }
  }
}

// Poll every 30 seconds
setInterval(pollLogs, 30000);

Example: Processing Webhooks

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/sim-webhook', (req, res) => {
  // Verify signature
  const signature = req.headers['sim-signature'];
  const body = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Check timestamp to prevent replay attacks
  const timestamp = parseInt(req.headers['sim-timestamp']);
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  
  if (timestamp < fiveMinutesAgo) {
    return res.status(401).send('Timestamp too old');
  }
  
  // Process the webhook
  const event = req.body;
  
  switch (event.type) {
    case 'workflow.execution.completed':
      const { workflowId, executionId, status, cost } = event.data;
      
      if (status === 'error') {
        console.error(`Workflow ${workflowId} failed: ${executionId}`);
        // Handle error...
      } else {
        console.log(`Workflow ${workflowId} completed: ${executionId}`);
        console.log(`Cost: $${cost.total}`);
        // Process successful execution...
      }
      break;
  }
  
  // Return 200 to acknowledge receipt
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});