> ## 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.
`settings.metrics` is the complete organization dashboard metric list: sending it replaces the
previous list rather than appending one item. Never construct the request from the new metric alone.

Use this sequence for a new dashboard metric:

1. Read the exact organization with `GET /api/v2/account?targetAccountId=...` and retain the complete
   current `settings.metrics` array, including its order and every property on every definition.
2. If the array is absent or empty but the user expects existing dashboard metrics, stop. The panel
   can display inherited or standard defaults that are not an authored organization array. Do not
   create a one-metric override without confirming the complete panel the user wants.
3. Query a bounded sample of the underlying logs and verify the expected records and fields.
4. Submit the proposed definition to `POST /api/v2/logs/timeSeries`.
5. Check the metric value together with `eventCount`; a rate without its denominator is incomplete.
6. Upsert by the stable metric `name`: replace only the matching entry or append the new entry to the
   retained array. Submit that complete array through `POST /api/v2/account`.
7. Re-read the organization and verify that every prior metric name remains, the intended metric is
   correct, and no unrelated definition or property changed.

Do not issue a second write automatically if verification finds unexpected removals; report the
mismatch and reconcile against the retained pre-write list first.

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>