Create incidents manually

Manual incidents are great for reporting time-sensitive issues that your monitors won't catch — like "The site is up, but payments are failing." They're typically reported by colleagues in non-technical roles who spot a problem before any alert fires.

From the incidents dashboard

1. Go to Better Stack → Incidents.
2. Click Report a new incident in the upper-right corner.
3. Describe the issue and optionally attach screenshots or files.
4. Select who should get notified.
5. Click Create new incident.

Via a shareable URL

To let colleagues who don't have a Better Stack account report incidents, share your secret incident form URL. Anyone with the link can submit an incident without signing in.

1. Go to Better Stack → Incidents.
2. Click Report a new incident.
3. Copy the URL shown at the top of the page.
4. Share it in your company's Slack or internal wiki.

Using an escalation policy

Escalation policies give you a dedicated incident form with predefined escalation steps. Reporters only describe the issue — no need to choose who gets notified. This is especially useful when different teams own different services: each team gets their own policy and form, so incidents always reach the right people automatically.

With metadata-based routing, you can go further. Add metadata fields to your policy — such as Service or Environment — and route incidents to different responders based on the values filled in. A production database incident can page the on-call engineer, while a staging incident only sends an email.

1. Go to Better Stack → Escalation policies → Add escalation policy.
2. Configure the escalation steps and, optionally, add metadata fields and routing rules.
3. Save the policy.
4. Click Report a new incident on the policy page to open or share the policy-specific form.

The form skips the notification channel step entirely — escalation is handled by the policy. If you added metadata fields, reporters fill those in instead.

From Slack

Use the /incident slash command in any Slack channel connected to Better Stack:

/incident New users can't sign up

A modal opens with Brief description, In-depth description, and Who should we notify? fields. Click Report incident to submit.

Add metadata to incidents

Metadata lets you attach key-value information to an incident — such as Service, Environment, or Team. Use it to route incidents to the right responders, filter the incidents list, and control the status of of status page resources.

Metadata fields are configured per Slack integration or escalation policy. See Metadata-based routing for setup instructions.

In the incident form: Metadata fields appear at the bottom of the form when your team has them configured. Fill them in before submitting.

In Slack: Metadata works the same way. After selecting a team or escalation policy in the Who should we notify? dropdown, any configured metadata fields appear in the modal automatically.

Using the API

Use POST /api/v3/incidents to create incidents programmatically. See the full API reference for all available attributes.

curl --request POST \
  --url https://uptime.betterstack.com/api/v3/incidents \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "summary": "Users can'\''t sign up",
    "requester_email": "alice@example.com",
    "description": "500 errors on the login page since 14:30 UTC.",
    "metadata": {
      "Service": [{ "value": "Payments" }],
      "Environment": [{ "value": "Production" }]
    }
  }'

Required attributes

• summary — Brief description of the incident.
• requester_email — Email of the person reporting.

Optional attributes

• description — In-depth description.
• call, sms, email, push — Notification channels (true or false).
• team_wait — Seconds to wait before alerting the entire team. Default is 180. Set to null to never alert the entire team.
• policy_id — ID of the escalation policy to use.
• metadata — Key-value pairs to attach to the incident.

Other ways to trigger incidents

Email integration

Send an email to your integration's unique inbox address and Better Stack creates an incident automatically. This is useful for monitoring tools or services that send email alerts and need to page your on-call team.

See Email integration for setup instructions.

Incoming webhooks

POST a payload to your webhook's unique URL and Better Stack creates an incident based on your configured rules. This is useful for connecting custom systems or third-party tools that support outbound webhooks.

See Incoming webhooks for setup instructions.

Call routing

Provision a phone number and anyone who calls it immediately triggers an incident. Better Stack then routes the call to your on-call team. This is useful for non-technical colleagues who need a simple way to escalate urgent issues.

See Call routing for setup instructions.