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

# Logs, conversations, and reporting

> Trace Agent work from summary logs to complete conversations and measurable outcomes.

Vida exposes summary logs, complete conversations, Contact and Task references, and aggregate time-series reporting. Choose the narrowest source that proves the claim you need to make.

## Design measurement before deployment

Start with the business outcome, then choose the record that represents it:

* Use a **conversation** when each completed interaction is one observation.
* Use a **Task attempt** when unanswered, failed, or delivery-only attempts belong in the population.
* Use one **terminal Task outcome** when a retry sequence should count once rather than once per attempt.

Add a typed reporting field only when standard log fields do not already describe the outcome. Give
it a stable key, prefer boolean, choices, or number over free text, and state when the value should be
`null`. Test successful, negative, and inconclusive conversations before using that field in a metric.

Keep the population and denominator explicit. A conversion rate over completed conversations, a
contact rate over all attempts, and a final yield over Tasks answer different questions even when
they use the same Agent.

## Query bounded logs

Use `GET /api/v2/logs` with `targetAccountId` and a bounded `start` and `end` range for routine analysis. Select only required fields and filters. Use CSV for large exports; follow pagination for JSON results.

Log filters support the comparison options documented in OpenAPI. Request field metadata when building a new integration rather than assuming every account produces the same custom reporting fields.

## Expand a conversation

A log, Task attempt, or Contact communication entry can include a conversation reference with `roomId` and message `uuid`.

* Read one complete conversation with `/api/v2/conversation/{roomId}/{uuid}`.
* Read room messages with `/api/v2/messages/{roomId}`.
* Use the batch conversation route for a bounded set of lookups.

Do not treat a Task enqueue, outbound request, or summary log as proof that a conversation occurred or that its goal was met.

## Build an incident packet

For a customer-impacting event:

1. Query the exact time window and account scope.
2. Identify affected Task, room, conversation, and Agent IDs.
3. Expand the relevant conversations.
4. Establish a timeline from source timestamps.
5. Separate observed impact from inferred cause.
6. Recommend a bounded remediation and verification step.

Keep raw service diagnostics separate from customer-facing conclusions.

## Calculate comparable metrics

Use `POST /api/v2/logs/timeSeries` for aggregate and time-bucketed results. Define the population, denominator, formula, aggregation, scaling, and time range explicitly.

For reporting-field rates, decide how null values affect the denominator. For retry workflows, decide whether the metric measures attempts or one terminal outcome per Task. Filter Task attempts explicitly when attempts without conversations belong in the population.

Validate a metric against live data before saving it to organization dashboard settings. Preserve unrelated stored metrics when updating the settings array.

Use this sequence for a new dashboard metric:

1. Query a bounded sample of the underlying logs and verify the expected records and fields.
2. Submit the proposed definition to `POST /api/v2/logs/timeSeries`.
3. Check the metric value together with `eventCount`; a rate without its denominator is incomplete.
4. Compare the result with the source records, including null and failed-attempt behavior.
5. Save the verified definition in the organization account's `settings.metrics` array while
   preserving unrelated metrics, then re-read the account.

Use `minimumSampleSize` when small groups or time buckets should not produce a displayed result.
For an Agent experiment, filter results by `experiments.id` and `experiments.variant`, and keep the
metric definition, audience, channel mix, and time range comparable across variants.

<Note>
  For metric definitions, Task-outcome filters, and incident workflow details, use the [Vida API Skill](/docs/api-reference/vida-api-skill).
</Note>