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

# Retrieve run logs by AI contact

> Returns the run logs (tree structure with descendants) for a given AI contact, ordered by start time descending. Supports pagination over the root run logs.

## Overview

Retrieve the AI run logs (assistant execution traces) associated with a specific AI contact. Each run log is returned as a full tree with its descendants, ordered from the most recent root run to the oldest.

Use this endpoint to inspect what the AI did during a conversation: which assistants were used, which tools were called, what predefined behaviours triggered, and the input/output of each step.

## Use Cases

* **Debug Assistant Behaviour**: Inspect tool calls, context retrieval, and decisions step-by-step
* **Audit & Compliance**: Build an audit trail of AI actions taken per contact
* **Analytics**: Compute per-contact metrics about AI runs, tool usage, latency
* **Customer Support**: Understand why the assistant replied in a certain way to a given contact

## Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

```
x-api-key: your_api_key_here
```

## Query Parameters

| Parameter       | Type          | Required | Description                                                |
| --------------- | ------------- | -------- | ---------------------------------------------------------- |
| `ai_contact_id` | string (UUID) | Yes      | UUID of the AI contact whose run logs you want to retrieve |
| `page`          | integer       | No       | Page number (defaults to `1`)                              |
| `page_size`     | integer       | No       | Items per page (defaults to `20`, max `100`)               |

Pagination applies to the **root** run logs only. Each root is returned together with its full descendant tree.

## Response Structure

| Field       | Type    | Description                                                 |
| ----------- | ------- | ----------------------------------------------------------- |
| `page`      | integer | Current page number                                         |
| `page_size` | integer | Page size used to compute the response                      |
| `total`     | integer | Total number of root run logs for the contact               |
| `run_logs`  | array   | Array of root run logs, each containing nested `children[]` |

### Run Log Object

| Field           | Type           | Description                                                                 |
| --------------- | -------------- | --------------------------------------------------------------------------- |
| `id`            | string (UUID)  | Run log unique identifier                                                   |
| `run_type`      | string         | Type of run (e.g. `master`, `tool_call`, `predefined_behaviour`, `context`) |
| `status`        | string         | One of `pending`, `running`, `success`, `failed`                            |
| `content`       | object \| null | Type-specific payload (inputs/outputs, parameters, etc.)                    |
| `error`         | object \| null | Error details if the run failed                                             |
| `start_time`    | string (ISO)   | Timestamp when the run started                                              |
| `end_time`      | string (ISO)   | Timestamp when the run finished (null if still running)                     |
| `ai_contact_id` | string (UUID)  | AI contact this run belongs to                                              |
| `parentId`      | string \| null | Parent run log id (null for root run logs)                                  |
| `children`      | array          | Child run logs (recursively, same shape)                                    |

## Example Request

```bash theme={null}
curl -X GET "https://api.vambe.me/api/public/run-logs?ai_contact_id=df980fc8-b6db-4820-bf22-2969482d106d&page=1&page_size=20" \
  -H "x-api-key: your_api_key_here"
```

## Error Responses

| Status Code | Description                                  |
| ----------- | -------------------------------------------- |
| 400         | Bad Request - Invalid `ai_contact_id` format |
| 401         | Unauthorized - Invalid or missing API key    |
| 404         | Not Found - AI contact does not exist        |
| 500         | Internal Server Error - Something went wrong |


## OpenAPI

````yaml get /api/public/run-logs
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/public/run-logs:
    get:
      tags:
        - Run Logs
      summary: Retrieve run logs by AI contact
      description: >-
        Returns the run logs (tree structure with descendants) for a given AI
        contact, ordered by start time descending. Supports pagination over the
        root run logs.
      operationId: PublicRunLogV2Controller_getRunLogsByAiContact
      parameters:
        - name: x-api-key
          in: header
          description: API key required to authorize the request
          required: true
          schema:
            type: string
        - name: ai_contact_id
          required: true
          in: query
          description: UUID of the AI contact to fetch run logs for
          schema:
            type: string
        - name: page
          required: false
          in: query
          description: Page number (defaults to 1)
          schema:
            type: number
        - name: page_size
          required: false
          in: query
          description: Page size (defaults to 20, max 100)
          schema:
            type: number
      responses:
        '200':
          description: Run logs retrieved successfully.
        '404':
          description: AI contact not found.

````