Connections

Data Syntax: $ vs @

Use $blockname.column for uploaded data blocks (CSV/Excel) and @connection.field for external connections. Use lowercase with underscores for connection names (e.g., sales_data).

$sales.revenue
@stripe.mrr
@airtable.row.column

Using Connections in Formulas

Type @ in any formula field to trigger autocomplete. For structured data like Airtable, use @connection_name.row.column to access specific cells.

base_revenue * @assumptions.growth_rate
$sales.revenue * (1 + @analytics.user_growth)
@stripe.mrr * 12 * (1 - @analytics.churn_rate)

Manual

Enter field names and values directly. Use for assumptions you want to change quickly without editing individual blocks.

Go to /connections → Add Connection → Manual. Add fields with names and numeric values.

Webhook

Webhooks let external tools push data to Carlo. Use them with Zapier, Make (Integromat), n8n, or any system that can send HTTP requests.

Payload format

Send a JSON object with numeric field values. Include the secret in the X-Webhook-Secret header.

{
  "monthly_revenue": 125000,
  "active_users": 3420,
  "conversion_rate": 0.045
}

PostHog

Pull analytics data directly from PostHog. Use your actual user metrics, event counts, and custom HogQL queries.

Available presets

@posthog.total_events_7d
@posthog.unique_users_7d
@posthog.pageviews_7d
@posthog.sessions_7d

Custom HogQL queries

SELECT event as name, count() as value 
FROM events 
WHERE timestamp > now() - INTERVAL 30 DAY 
GROUP BY event

Stripe

Pull billing metrics directly from Stripe. Use your actual MRR, customer counts, and revenue data in forecasts.

Available metrics

@stripe.mrr
@stripe.arr
@stripe.total_customers
@stripe.active_subscriptions
@stripe.revenue_30d
@stripe.new_customers_30d

Airtable

Sync values from Airtable bases. Great for team-managed assumptions and structured data that doesn't fit in a simple spreadsheet.

Table format

Your table can have multiple numeric columns. The first text column is used as the row identifier, and all numeric columns are synced using dot notation.

Hierarchical references

Access specific cells using @connection.row.column syntax:

@revenue.product_a.q1  → 100
@revenue.product_a.q2  → 200
@revenue.product_b.q1  → 150

total = @revenue.product_a.q1 + @revenue.product_b.q1

Notion

Connect Notion databases to use structured data from your existing workflows. Great for product roadmaps, resource planning, or team-managed assumptions.

Database format

Your Notion database needs two properties: a title property for field names and a number property for values.

REST API

Fetch data from any HTTP endpoint that returns JSON. Connect to internal APIs, third-party services, or custom data sources.

JSON path syntax

Use JSON path to extract specific values from the API response.

{
  "data": {
    "metrics": {
      "revenue": 125000,
      "users": 3420
    }
  }
}

$.data.metrics.revenue  → 125000
$.data.metrics.users    → 3420

Authentication

Add custom headers for API keys or bearer tokens. Headers are stored securely and sent with each request.

Auto-Refresh & Data Freshness

In-app runs

When you click Run in the app, Carlo fetches the latest values from all connected sources before running the simulation. Your results always reflect current data.

Embedded models

Embeds use cached connection data for instant loading. When someone views your embed, Carlo checks if the cache is older than 30 minutes. If stale, a background refresh triggers automatically—the viewer sees cached results immediately while fresh data syncs for the next viewer.

Manual sync

Trigger a manual sync from the connections page at any time. This updates the cache immediately, affecting both in-app runs and embeds.

Sync status

Each connection shows its last sync time and status. If a sync fails, you'll see an error message with details to help troubleshoot.