---
title: "Conversations API | Grafana Cloud documentation"
description: "Start or continue Assistant conversations, fetch messages, and stream chat events with the Grafana Assistant HTTP API."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Conversations API

Use conversations to start, continue, inspect, and stream Assistant interactions.

Examples use the base URL and service account token described in [Grafana Assistant HTTP API reference](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis).

## Start or continue a conversation

Create a new conversation with the Assistant or continue an existing one.

**Endpoint**

`POST /assistant/chats`

**Permissions**

The service account must have these Assistant RBAC permissions:

- `grafana-assistant-app.chats:access`

The service account also needs any Grafana RBAC permissions required by the prompt, such as data source query or dashboard read permissions.

**Request**

Send a JSON request body.

Expand table

| Field    | Required | Description                                     |
|----------|----------|-------------------------------------------------|
| `prompt` | Yes      | The task or question for Assistant.             |
| `chatId` | No       | The ID of an existing conversation to continue. |

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "prompt": "How many datasources do I have?",
  "chatId": "optional-existing-chat-id"
}
```

**Response**

The response includes the conversation ID to use when fetching messages or streaming events.

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "status": "success",
  "data": {
    "chatId": "18289896-b393-4136-9014-c2630a62f67f"
  }
}
```

**Examples**

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
curl -X POST "${ASSISTANT_API_URL}/assistant/chats" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "prompt": "How many datasources do I have?"
  }'
```

Use the returned `chatId` to fetch messages or stream chat events.

Only one Assistant task can be active for an existing chat. If you submit another request while a task is running, the API returns HTTP `409 Conflict`. Wait for the active task to finish before retrying.

## Fetch conversation messages

Retrieve the current chat metadata and messages.

**Endpoint**

`GET /chats/{chatId}`

**Permissions**

The service account must have these Assistant RBAC permissions:

- `grafana-assistant-app.chats:access`

**Request**

Expand table

| Parameter | Required | Description                                                             |
|-----------|----------|-------------------------------------------------------------------------|
| `chatId`  | Yes      | The conversation ID returned when you start or continue a conversation. |

**Response**

The response includes conversation metadata and messages.

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "status": "success",
  "data": {
    "id": "18289896-b393-4136-9014-c2630a62f67f",
    "name": "Assistant Conversation",
    "created": "2025-10-20T10:30:00Z",
    "modified": "2025-10-20T10:35:00Z",
    "userId": "sa-5594@serviceaccount.grafana",
    "category": "assistant",
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "How many datasources do I have?"
          }
        ]
      },
      {
        "id": "msg-2",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "You have 5 datasources configured..."
          }
        ]
      }
    ]
  }
}
```

**Examples**

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
CHAT_ID="18289896-b393-4136-9014-c2630a62f67f"

curl -X GET "${ASSISTANT_API_URL}/chats/${CHAT_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
```

## Stream chat events

Subscribe to real-time conversation updates using SSE.

**Endpoint**

`GET /api/events/chats/{chatId}`

This endpoint uses a different base path than standard `api/v1` endpoints:

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/events/chats/{chatId}
```

The example uses `ASSISTANT_EVENTS_URL` as shorthand for the events base URL:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
ASSISTANT_EVENTS_URL="https://your-stack.grafana.net/api/plugins/grafana-assistant-app/resources/api/events"
```

**Permissions**

The service account must have these Assistant RBAC permissions:

- `grafana-assistant-app.chats:access`

**Request**

Expand table

| Parameter | Required | Description                                                             |
|-----------|----------|-------------------------------------------------------------------------|
| `chatId`  | Yes      | The conversation ID returned when you start or continue a conversation. |

**Response**

The response is an SSE stream. Listen for the event types your integration needs.

Expand table

| Event type                | Description                                 |
|---------------------------|---------------------------------------------|
| `message.created`         | A new message is added to the conversation. |
| `message.stream.start`    | A message starts streaming.                 |
| `message.content.delta`   | An incremental update to message content.   |
| `message.stream.complete` | A message finishes streaming.               |
| `AGENT_STARTED`           | Assistant begins working on the task.       |
| `AGENT_COMPLETED`         | Assistant finishes successfully.            |
| `AGENT_FAILED`            | Assistant encounters an error.              |
| `REMOTE_TOOL_REQUEST`     | Assistant requests frontend tool execution. |

**Examples**

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
CHAT_ID="18289896-b393-4136-9014-c2630a62f67f"

curl -N "${ASSISTANT_EVENTS_URL}/chats/${CHAT_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -H "Accept: text/event-stream"
```

For integration examples:

1. Open **Grafana Assistant** from the main navigation.
2. Click **Integration hub**.
3. Review the SDK and integration examples. Direct HTTP API testing may not be available from the Integration hub.