> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Better Stack

> Connect Better Stack to CloudThinker

Connect your Better Stack account to enable CloudThinker agents to monitor uptime, triage incidents, view on-call schedules, and search logs across your observability stack.

Better Stack uses **OAuth**, so there are no API keys to create or paste. You authorize CloudThinker once from inside Better Stack, scoped to your account's access.

***

## Supported Services

CloudThinker connects to the official Better Stack MCP server, spanning two surfaces:

| Service       | What it covers                                                                        |
| ------------- | ------------------------------------------------------------------------------------- |
| **Uptime**    | Monitors, heartbeats, incidents, on-call schedules, escalation policies, status pages |
| **Telemetry** | Log and metric queries, sources, dashboards, charts, alerts, error tracking           |

***

## Prerequisites

* A **Better Stack account** with access to the team you want to connect.
* Permission to authorize third-party apps for that team.

<Info>
  OAuth scopes the connection to what your Better Stack user can already see. Connect with the least-privileged user that works.
</Info>

***

## Setup

<Steps>
  <Step title="Open CloudThinker">
    Navigate to **Connections → Better Stack** in your CloudThinker workspace.
  </Step>

  <Step title="Start the OAuth flow">
    Click **Connect** to open Better Stack's authorization page.
  </Step>

  <Step title="Authorize CloudThinker">
    Sign in, choose the team to connect, and approve access.
  </Step>

  <Step title="Return to CloudThinker">
    You're redirected back with a **Connected** status, ready for all agents.
  </Step>
</Steps>

<Tip>
  To switch teams or revoke access, disconnect in CloudThinker and reconnect, or remove the authorization in Better Stack's app settings.
</Tip>

***

## Required Permissions

CloudThinker inherits the authorizing user's visibility within the connected team.

* **Read operations** (monitors, incidents, on-call, logs, metrics) work with standard member access.
* **Write operations** (acknowledging incidents, publishing reports, editing dashboards or alerts) need matching Better Stack permissions **and** explicit [approval](/guide/approval) in CloudThinker.

***

## Agent Capabilities

Once connected, agents have broad read access and approval-gated write access.

### Read Capabilities

| Category                | What the agent can do                                                   |
| ----------------------- | ----------------------------------------------------------------------- |
| **Monitors**            | List monitors, inspect availability % and response times over a window  |
| **Heartbeats**          | Inspect cron/scheduled-job heartbeats and hit-rate                      |
| **Incidents**           | List and inspect incidents, timelines, comments, and escalation options |
| **On-Call**             | View on-call schedules, current rotations, and shift events             |
| **Escalations**         | Inspect escalation policies and severity definitions                    |
| **Status Pages**        | List status pages, tracked components, and past reports                 |
| **Logs (Telemetry)**    | Search logs scoped to a source, inspect source fields and config        |
| **Metrics**             | Query metrics and inspect cardinality                                   |
| **Dashboards & Charts** | List and inspect dashboards, charts, and templates                      |
| **Alerts**              | List and inspect chart alerts                                           |
| **Errors**              | List recent errors and inspect error groups                             |

### Write Capabilities

| Category                | What the agent can do                                                |
| ----------------------- | -------------------------------------------------------------------- |
| **Incidents**           | Acknowledge, resolve, reopen, escalate, comment, or create incidents |
| **Status Pages**        | Publish status page reports and updates                              |
| **Dashboards & Charts** | Create, edit, rename, or remove dashboards and charts                |
| **Alerts**              | Create, edit, delete, or pause chart alerts                          |
| **Errors**              | Update error state (resolve / ignore)                                |

<Warning>
  Writes change live monitoring and incident state. CloudThinker requires explicit [approval](/guide/approval), naming the resource, before any write runs.
</Warning>

### Example Prompts

```bash theme={null}
@tony list open Better Stack incidents and #alert on anything hitting production
@tony summarize incidents from the last 24h and #recommend follow-ups
@tony search api-gateway logs for 5xx in the last hour and #visualize by status code
@tony report 24h availability for production monitors and #flag anything below 99%
```

<Note>
  Log search is **scoped per source**, so there's no global search. Name the source (e.g. `api-gateway`) so the agent can resolve it before querying.
</Note>

***

## Troubleshooting

<Accordion title="Connection fails with 401 Unauthorized">
  The OAuth token expired or access is insufficient. Disconnect and reconnect.
</Accordion>

<Accordion title="A resource returns 404 Not Found">
  The resource belongs to a different team or was deleted. Re-list it in the connected team to get current IDs.
</Accordion>

<Accordion title="Requests fail with 429 Too Many Requests">
  You've hit Better Stack's rate limit. Agents back off and retry automatically.
</Accordion>

<Accordion title="Log query returns a syntax error">
  Better Stack uses Live Tail syntax. Ask the agent to load the query instructions for the source, then refine.
</Accordion>

***

## Security Best Practices

* **Least-privilege user** - Authorize with only the access CloudThinker needs
* **Approval for writes** - Keep writes approval-gated so incident and status-page changes stay deliberate
* **Scoped teams** - Limit the authorizing user's team membership to what CloudThinker should see
* **Revoke when unused** - Remove the authorization in Better Stack if you stop using it

***

## Related

<CardGroup cols={2}>
  <Card title="Datadog Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    Observability and monitoring
  </Card>

  <Card title="PagerDuty Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/pagerduty.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=cdc34a966d5d46da70c3bc509a2a7492" href="/guide/connections/pagerduty" width="24" height="24" data-path="images/icons/pagerduty.svg">
    Incident alerting and on-call
  </Card>
</CardGroup>