> ## 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 for uptime monitoring, incident triage, on-call visibility, and log search across your observability stack

Connect your Better Stack account to enable CloudThinker agents to monitor uptime, triage incidents, view on-call schedules, and search logs. Better Stack uses **OAuth** — you authorize CloudThinker once from inside Better Stack, scoped to the team you choose.

## 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. The connection shows a **Connected** status.
  </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>

## Connection details

Better Stack uses OAuth — there are no credential fields to store. CloudThinker holds the authorization token issued by Better Stack after you approve access.

## 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 read access to two Better Stack surfaces and approval-gated write access.

**Uptime**

| 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                 |

**Telemetry**

| Category                | What the agent can do                                            |
| ----------------------- | ---------------------------------------------------------------- |
| **Logs**                | 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 operations (approval-gated)**

| 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>

### Verify the connection

```text theme={null}
@alex list open Better Stack incidents and #alert on anything hitting production
```

### Example prompts

```text theme={null}
@alex summarize Better Stack incidents from the last 24h and #recommend follow-ups
@alex search api-gateway logs for 5xx in the last hour and #chart by status code
@alex report 24h availability for production monitors
```

<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

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Least-privilege user** — authorize with only the access CloudThinker needs; limit the authorizing user's team membership to what CloudThinker should see.
- **Revoke when unused** — remove the authorization in Better Stack's app settings if you stop using the connection.

## 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>