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

# Langfuse

> Connect Langfuse to CloudThinker for LLM trace investigation, conversation debugging, evaluation review, and prompt auditing

Connect your Langfuse project to enable CloudThinker agents to investigate LLM traces, debug conversations, review evaluation scores and datasets, and audit prompt versions across your observability stack. Langfuse authenticates with a **project-scoped API key pair** (a public key and a secret key) against your Langfuse host — the same setup works for Langfuse Cloud and self-hosted instances.

## Prerequisites

* A **Langfuse Cloud or self-hosted project** you want to investigate.
* A **project-scoped API key pair** (public key and secret key) from that project.
* Your **Langfuse host URL** (`https://cloud.langfuse.com` for EU, `https://us.cloud.langfuse.com` for US, or your self-hosted domain).

<Info>
  Langfuse API keys are scoped to a single project. Create the key pair in the project CloudThinker should reach, and use a key pair dedicated to CloudThinker so access is easy to audit and revoke.
</Info>

## Setup

<Steps>
  <Step title="Open Langfuse">
    Sign in to Langfuse and select the project you want CloudThinker to investigate.
  </Step>

  <Step title="Create an API key pair">
    Go to **Project → Settings → API Keys** and click **Create new API keys**. Langfuse generates:

    * A **Public Key** (prefixed `pk-lf-`)
    * A **Secret Key** (prefixed `sk-lf-`)

    Copy the secret key immediately — it is shown only once and cannot be retrieved later.
  </Step>

  <Step title="Add connection in CloudThinker">
    Navigate to **Connections → Langfuse** and enter:

    * **Host**: your Langfuse base URL, e.g. `https://cloud.langfuse.com` (base URL only, no path)
    * **Public Key**: the `pk-lf-` key you created
    * **Secret Key**: the `sk-lf-` key you created

    Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
  </Step>
</Steps>

<Warning>
  Copy the secret key immediately after creation. Langfuse shows it only once, so you'll need to create a new key pair if it's lost.
</Warning>

## Connection details

| Field                     | Description                                                             | Example                      |
| ------------------------- | ----------------------------------------------------------------------- | ---------------------------- |
| **LANGFUSE\_HOST**        | Base URL of your Langfuse instance — EU cloud, US cloud, or self-hosted | `https://cloud.langfuse.com` |
| **LANGFUSE\_PUBLIC\_KEY** | Project-scoped public key                                               | `pk-lf-...`                  |
| **LANGFUSE\_SECRET\_KEY** | Project-scoped secret key                                               | `sk-lf-...`                  |

## Required permissions

Langfuse API keys inherit the access of the project they belong to. CloudThinker uses the key pair for read and investigation workflows across traces, observations, metrics, scores, datasets, annotation queues, comments, and prompts.

<Tip>
  Follow least privilege: scope the key pair to the single project CloudThinker should investigate, and keep it separate from keys used by your SDKs or other integrations so it can be rotated or revoked independently.
</Tip>

## Agent capabilities

Once connected, agents can investigate LLM observability data across your Langfuse project.

| Capability            | Description                                                           |
| --------------------- | --------------------------------------------------------------------- |
| **Traces**            | Search and inspect traces, correlate errors, latency, and model usage |
| **Observations**      | Drill into spans, generations, and events within a trace              |
| **Metrics**           | Query usage, latency, and cost metrics over a time window             |
| **Scores**            | Review evaluation scores and quality signals                          |
| **Datasets**          | Inspect datasets used for evaluation and testing                      |
| **Annotation queues** | Review annotation queues and their items                              |
| **Comments**          | Read comments left on traces and observations                         |
| **Prompts**           | List prompt versions, labels, and recent changes for prompt audits    |

<Note>
  A CloudThinker chat URL carries a `conversationId` that maps to a Langfuse `sessionId`. Ask the agent to analyze the chat URL and it resolves the session through Langfuse rather than fetching the URL as a webpage.
</Note>

### Verify the connection

```text theme={null}
@alex investigate recent Langfuse traces and summarize errors, latency, and model usage
```

### Example prompts

```text theme={null}
@alex investigate recent failed Langfuse traces for production conversations, correlate errors and latency, and #recommend likely fixes
@alex inspect this CloudThinker chat URL by mapping its conversationId to a Langfuse session and summarize tool calls, model usage, and failures
@alex list active Langfuse prompts, versions, and labels, and #report prompts tied to degraded scores
```

Trace and metric queries are time-bounded, so mention a window (e.g. "the last hour") to keep results focused.

## Troubleshooting

<Accordion title="Connection fails with 401 Unauthorized">
  Verify the public and secret keys are correct and have not been rotated or deleted. Confirm both keys belong to the **same** Langfuse project and were copied without extra whitespace.
</Accordion>

<Accordion title="Wrong host or region">
  Data is separated per region, so a key pair only works against the host it was created in. Check that **LANGFUSE\_HOST** matches the URL you sign in to, e.g. `https://cloud.langfuse.com` for EU or `https://us.cloud.langfuse.com` for US.
</Accordion>

<Accordion title="Every request returns 404">
  **LANGFUSE\_HOST** has an extra path suffix. Set it to the base URL only, with no trailing path.
</Accordion>

<Accordion title="Searches return no results">
  Trace and metric searches need a time range. Ask the agent to use a recent window (e.g. the last hour) and widen it only if needed. Confirm the project is actively receiving traces from your application.
</Accordion>

<Accordion title="Chat URL is not analyzed as a session">
  Ask the agent to extract the `conversationId` and map it to a Langfuse `sessionId` instead of fetching the URL directly.
</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.

- **Project-scoped key pair** — use a key pair scoped to the single project CloudThinker investigates; create a dedicated pair for CloudThinker so access is easy to audit and revoke independently.
- **Correct host** — match the host to the region where the project lives to avoid cross-region failures.

## Related

<CardGroup cols={2}>
  <Card title="SigNoz Connection" icon="https://mintcdn.com/cloudthinker/CGWam0VVP8R5KVLk/images/icons/signoz.svg?fit=max&auto=format&n=CGWam0VVP8R5KVLk&q=85&s=d08abadb07adcc41c8812b59483344e3" href="/guide/connections/signoz" width="24" height="24" data-path="images/icons/signoz.svg">
    Logs, metrics, traces, and dashboards
  </Card>

  <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">
    Log search, metrics, and monitoring
  </Card>
</CardGroup>