Logs, conversations, and reporting

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.