---
title: "Datos, reportes y tareas"
description: "Los datos estructurados que capturan los agentes de Raíz como definiciones y hechos, los reportes construidos sobre ellos, el historial de cambios y las tareas que corren en segundo plano."
---

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

# Datos, reportes y tareas

Además de hablar, tus agentes capturan datos, como por qué llamó un paciente o qué sede prefiere. Decides qué capturar con las definiciones, y cada valor capturado para un contacto o una conversación es un hecho que registra quién lo escribió y de dónde salió. Los reportes convierten las conversaciones y los hechos en cifras, el historial de cambios registra quién cambió qué, y las tareas son los trabajos largos que corren en segundo plano.

## Definiciones

Una definición es una cosa que se captura:

| Campo | Qué es |
| --- | --- |
| `kind` | `attribute` (una propiedad), `category` (una clasificación), `metric` (un número medido, con una `unit` UCUM) o `assessment` (una evaluación, es decir, un juicio sobre una conversación; las evaluaciones de sí o no alimentan el reporte de evaluaciones). |
| `subject` | Qué describen sus hechos: un `contact` o una `conversation`. |
| `valueType` | `text`, `number`, `boolean`, `date` (`YYYY-MM-DD`) u `option`, con hasta 100 `options`, cada una con una `key` y una `label`. |
| `key` | Un nombre de máquina estable: letras minúsculas, dígitos y `_`, empezando por una letra. Una columna de CSV con este encabezado se [importa](/developers/raiz/contacts/#importar-desde-un-csv) en ella. |
| `name`, `instructions` | Su nombre para las personas, y cómo decide la IA el valor. |
| `agentIds` | Los agentes que la usan. Vacío: todos los agentes. |
| `status` | `draft` mientras la preparas, `active` cuando los agentes la usan y acepta hechos, o `retired`. |

[`raiz.definitions.create`](/api/raiz/definitions/create/) agrega una; una clave que ya usa una definición en borrador o activa responde `409 KEY_IN_USE`. [`raiz.definitions.update`](/api/raiz/definitions/update/) cambia una, con `expectedVersion`. Sus `options` y sus `agentIds` son conjuntos completos, y una opción que omites se retira, nunca se elimina, porque hay hechos que la usan. El tipo de valor y el sujeto no pueden cambiar una vez que la definición tiene hechos (`409 DEFINITION_TYPE_LOCKED`), y una definición retirada no puede cambiar en absoluto. [`raiz.definitions.list`](/api/raiz/definitions/list/) lista por defecto las definiciones en borrador y activas, por `kind`, `subject` y `status`.

## Hechos

Un hecho es el valor de una definición para un contacto o una conversación. Los contactos y las conversaciones vienen con sus hechos actuales, en `facts`: para cada definición, la afirmación más reciente que no fue rechazada, mientras que las anteriores quedan como historial. Cada hecho dice quién lo escribió (`author`: `person`, `ai`, `system`, `import` o `provider`), qué tan segura estaba la IA (`confidence`, de 0 a 1), cuándo se observó y su `reviewStatus`.

[`raiz.facts.create`](/api/raiz/facts/create/) registra un valor bajo una definición activa. El valor sigue el tipo de la definición: un texto, un número, un booleano, una fecha `YYYY-MM-DD` o la clave de una opción. Da `contactId` o `conversationId`, según cuál sea el sujeto de la definición. Di de dónde salió el valor con `reason` y, como evidencia, con el `sourceConversationId` de una conversación cerrada y su `sourceMessageId`. En este ejemplo, la definición es la sede preferida de un contacto, de tipo `option`, y `north` es una de sus claves de opción:

```bash
curl https://api.getarbol.com/v1/raiz/facts \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "definitionId": "def_01jd8xfm2n3p4q5r6s7t8v9w0x",
    "contactId": "cnt_01jd8x7c4d5e6f7g8h9j0k1m2n",
    "value": "north",
    "reason": "El paciente dijo que prefiere la sede Norte.",
    "sourceConversationId": "cnv_01jd8x8d5e6f7g8h9j0k1m2n3p"
  }'
```

`"valueStatus": "unknown"` o `"not_applicable"`, sin `value`, registra que no hay ninguno. [`raiz.facts.update`](/api/raiz/facts/update/) revisa un hecho: `confirmed` lo respalda, y `rejected` lo retira, así que la afirmación anterior vuelve a ser la actual.

## Reportes

[`raiz.reports.get`](/api/raiz/reports/get/) responde con las cifras detrás de una pregunta, y `name` elige el reporte:

| `name` | Filas | Filtros |
| --- | --- | --- |
| `conversations_daily` | Las conversaciones en las que participó la IA, por día, agente, tipo de canal y dirección, con éxitos, fallos, escalamientos y sentimiento negativo. | `agentId`, `channelType` |
| `booking_outcomes` | Agendamientos a partir de constancias de agendamiento verificadas, por día de finalización, agente e integración: citas nuevas, reprogramaciones, cancelaciones, y constancias fallidas, pendientes, no verificadas y duplicadas. | `agentId` |
| `tool_calls_daily` | Llamadas a herramientas por día, agente y herramienta, con fallos y duraciones. | `agentId` |
| `tool_calls` | Cada llamada a una herramienta, de la más reciente a la más antigua, sin sus entradas ni sus salidas. | `agentId` |
| `assessment_results_daily` | Resultados de las evaluaciones por día y definición: sí, no y desconocido. | `definitionId` |
| `pqrsf_daily` | Clasificación de PQRSF, resoluciones confirmadas y remisiones, a partir de los hechos `pqrsf_*`. | `agentId`, `channelType` |
| `campaign_progress` | Los destinatarios de cada campaña por estado. | `campaignId` |

Los reportes diarios cuentan los días en la zona horaria de la organización, de `from` a `to` (`YYYY-MM-DD`, ambos incluidos; los últimos 30 días por defecto). Un reporte tiene como máximo 1000 filas, y `hasMore` significa que debes reducir el rango o los filtros. Un filtro que el reporte no recibe responde `400 REPORT_FILTER_UNSUPPORTED`. En `booking_outcomes`, `createdCount` cuenta las citas nuevas que creó la IA, no las confirmaciones de citas existentes, y `confirmedCount` es otro nombre para lo mismo, así que nunca sumes los dos. Sus filas son constancias históricas, no el estado actual de una cita.

## Historial de cambios

[`raiz.changes.list`](/api/raiz/changes/list/) es el registro de auditoría: quién creó, actualizó o eliminó qué, cuándo y por qué, de lo más reciente a lo más antiguo. Cada cambio tiene el `resourceType` y el `resourceId`, la `action`, el `author` y el `authorId` (la persona o el cliente; ninguno para la IA ni para Raíz mismo), el `reason` cuando quien escribió dio uno, como `merge`, `contact_import` o `conversation_analysis`, y, en una actualización, cada campo cambiado con su valor `from` y `to`. Filtra por `resourceId`, `resourceType`, `contactId` (con los duplicados que absorbió), `authorId`, `createdAfter` y `createdBefore`. Los valores pueden incluir datos personales de los contactos; leer el historial requiere el permiso (scope) `raiz:changes:read`.

## Tareas

Los trabajos largos corren en segundo plano como tareas: importaciones de contactos (`contact_import`), reanálisis de conversaciones (`analysis_run`) y rastreos de sitios web (`knowledge_crawl`). [`raiz.tasks.get`](/api/raiz/tasks/get/) lee una; después de que una acción devuelve una tarea, vuelve a consultarla cada pocos segundos. [`raiz.tasks.list`](/api/raiz/tasks/list/) las lista, de la más reciente a la más antigua, por `kind` y `status`:

| `status` | Significado |
| --- | --- |
| `queued`, `running` | En espera, o trabajando. `progress` cuenta los pasos de una tarea dividida en partes. |
| `completed` | Terminada. `result` contiene lo que produjo, como los conteos de una importación. |
| `failed` | `errorCode` dice por qué, y `retryable`, si puede volver a ejecutarse. |
| `cancelled` | Detenida a petición. Lo que ya hizo queda hecho. |

[`raiz.tasks.cancel`](/api/raiz/tasks/cancel/) cancela de inmediato una tarea en cola, y le pide a una que está corriendo que se detenga en su siguiente punto de control (`cancelRequestedAt`); pedirlo de nuevo no cambia nada. [`raiz.tasks.retry`](/api/raiz/tasks/retry/) vuelve a poner en cola una tarea fallida, desde donde se detuvo. Una tarea de un tipo que nunca se reintenta, o que agotó todos sus intentos, responde `409 TASK_NOT_RETRYABLE`.

Source: https://docs.getarbol.com/developers/raiz/data/index.mdx