Documentation

Get up and running with Status Blocks in just a few minutes. Here's what you need to do:

curl -X POST http://status-blocks.com/api/events \
  -H "Authorization: Bearer sb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"event": "user_signup", "user_id": "123"}'

Projects are the core organisational unit in Status Blocks. Each project has its own set of metrics, events, tracked users, and funnels.

Creating a project

Navigate to your dashboard and click Create Project. You'll need to provide:

• Name: A descriptive name for your project (e.g. "My SaaS App", "E-commerce Store")
• Template: Choose a pre-built template or start blank

API keys

Each project has a unique API key used to authenticate requests. You can find and regenerate your API key in your project's Settings tab. API keys use the format sb_ followed by a 60-character random string.

Project limits

The number of projects you can create depends on your plan. You can see your current limits in your billing settings.

Templates are pre-built metric packs designed for common use cases. When you create a project with a template, all the relevant metrics are automatically configured for you.

You can also apply templates after project creation via the API. All template metrics can be customised or deleted after they're created.

Metrics are the building blocks of your dashboard. Each metric is defined by a calculation type, an event to track, and optional filters.

Calculation types

Configuring a metric

When creating or editing a metric, you can configure:

• Name and description: How the metric appears on your dashboard
• Icon: An emoji to visually identify the metric
• Unit: Display unit (e.g. $, %, users)
• Event name: Which event to track (or * for all events)
• Value field: Which field to use for sum/average calculations
• Metadata filters: Only count events matching specific metadata values

Time periods

Metrics are automatically calculated across multiple time periods:

• Today — Events from the current day
• This week — Events from the current week
• This month — Events from the current month
• This year — Events from the current year
• All time — All events within your data retention period

Last Seen metrics

The Last Seen calculation type returns the number of seconds since the most recent matching event was received. This is useful for monitoring whether expected events are still arriving on schedule.

For example, if your application sends a heartbeat event every 60 seconds, you can create a Last Seen metric filtered to that event and set an alert for when the value goes above 120 — meaning no heartbeat has been received in over 2 minutes.

Alerts

You can set up alerts on any metric to be notified when a value goes above, below, or equals a threshold. Configure the alert operator, threshold value, and notification frequency (daily or once) in the metric settings.

Formula metrics let you create calculated values by combining other metrics using mathematical expressions.

Syntax

Formulas reference other metrics by their slug (the URL-friendly version of the metric name). You can use standard mathematical operators:

Examples

Rules

• Formulas cannot reference themselves (no self-referencing)
• Circular dependencies are detected and prevented (e.g. metric A referencing metric B which references metric A)
• Division by zero returns 0 rather than an error
• You can validate formula syntax before saving via the API

Events are the raw data that powers your metrics. Every time something happens in your application — a user signs up, makes a payment, views a page — you send an event to Status Blocks.

Event fields

How events flow into metrics

When an event is received, Status Blocks automatically recalculates all relevant metrics and updates your dashboard. If a user_id is included, the tracked user's profile is also updated.

Batch events

For bulk imports or high-throughput scenarios, use the batch endpoint to send up to 100 events in a single request. See the API Reference for details.

Viewing events

You can browse all events for a project in the Events tab. Events are displayed in reverse chronological order and can be searched and filtered.

When you include a user_id in your events, Status Blocks automatically creates and maintains user profiles.

How it works

• The first event with a new user_id automatically creates a tracked user
• Subsequent events update the user's last seen timestamp
• If you include user_email or user_name, the user profile is enriched with that information
• Per-user metrics are automatically tracked, including total events and total revenue

User profiles

The Users tab in your project shows all tracked users. You can:

• Browse and search users by ID or email
• View individual user profiles with their complete event history
• See per-user calculated metrics (total events, total revenue)
• See when a user was first seen and last active

Funnels let you track how users progress through a series of steps, helping you identify where users drop off in key flows.

Setting up a funnel

Navigate to the Funnels tab in your project to create a new funnel. You'll need to define:

• Funnel name: A descriptive name (e.g. "Signup to Payment")
• Steps: Two or more events that represent stages in the flow (e.g. page_view → user_signup → subscription_payment)
• Conversion window: The maximum number of days a user has to complete the funnel (1–365 days)

Funnel analysis

Once a funnel is created, Status Blocks calculates the following for each step:

Example funnel

Teams let you collaborate with others on your projects. Every account belongs to a team, and all projects are owned by a team.

Roles

Inviting team members

Team owners and admins can invite new members from Settings → Team. Invitations are sent by email and expire after a set period. The number of team members allowed depends on your plan.

Managing your team

• Change team name and billing email in Settings → Team
• Change member roles or remove members
• View pending invitations

Status Blocks offers a free plan and paid plans with increased limits and features. Payments are processed securely through Paddle.

Plans

See our pricing page for current plan details and limits. Plans differ in:

• Number of projects
• Number of team members
• Events per month
• Metrics per project
• Data retention period
• Features (integrations, advanced analytics, CSV export, custom domains)

Subscribing

Upgrade from Settings → Billing. Choose between monthly and yearly billing (yearly saves 20%). Payment is handled through a secure Paddle checkout overlay.

Cancelling

You can cancel your subscription at any time from Settings → Billing. When you cancel:

• Your subscription enters a grace period until the end of the current billing cycle
• You retain access to all paid features during the grace period
• You can resume your subscription at any time during the grace period
• After the grace period, your account reverts to the free plan