Skip to main content
GET
/
api
/
public
/
run-logs
Retrieve run logs by AI contact
curl --request GET \
  --url https://api.vambe.me/api/public/run-logs \
  --header 'x-api-key: <x-api-key>'

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.

​
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

ParameterTypeRequiredDescription
ai_contact_idstring (UUID)YesUUID of the AI contact whose run logs you want to retrieve
pageintegerNoPage number (defaults to 1)
page_sizeintegerNoItems 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

FieldTypeDescription
pageintegerCurrent page number
page_sizeintegerPage size used to compute the response
totalintegerTotal number of root run logs for the contact
run_logsarrayArray of root run logs, each containing nested children[]

​
Run Log Object

FieldTypeDescription
idstring (UUID)Run log unique identifier
run_typestringType of run (e.g. master, tool_call, predefined_behaviour, context)
statusstringOne of pending, running, success, failed
contentobject | nullType-specific payload (inputs/outputs, parameters, etc.)
errorobject | nullError details if the run failed
start_timestring (ISO)Timestamp when the run started
end_timestring (ISO)Timestamp when the run finished (null if still running)
ai_contact_idstring (UUID)AI contact this run belongs to
parentIdstring | nullParent run log id (null for root run logs)
childrenarrayChild run logs (recursively, same shape)

​
Example Request

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 CodeDescription
400Bad Request - Invalid ai_contact_id format
401Unauthorized - Invalid or missing API key
404Not Found - AI contact does not exist
500Internal Server Error - Something went wrong

Headers

​
x-api-key
string
required

API key required to authorize the request

Query Parameters

​
ai_contact_id
string
required

UUID of the AI contact to fetch run logs for

​
page
number

Page number (defaults to 1)

​
page_size
number

Page size (defaults to 20, max 100)

Response

Run logs retrieved successfully.