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. 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.