---
title: Exportación de datos
section: Cody Academy / Public API
updated: 2026-11-05
source: https://docs.cody-tech.com/academy/public-api/exportacion-de-datos
markdown: https://docs.cody-tech.com/academy/public-api/exportacion-de-datos.md
---

# Exporta las conversaciones de tu equipo, misión por misión

> **Guía de Cody Academy · Public API.** Esta guía te lleva de principio a fin para sacar de Cody las conversaciones de tu equipo con sus agentes y llevarlas a tu herramienta de reportes, tu data warehouse o una hoja de cálculo: crear la credencial, conseguir el token, encontrar los IDs, filtrar por misión, fechas, personas o agente, descargar todas las páginas y convertir el resultado a CSV. Todos los ejemplos usan datos simulados con el mismo formato que entrega la Public API.
>
> Para equipos de TI, analistas de datos e integradores · Necesitas poder hacer solicitudes HTTP desde un servidor o un script.
>
> Versión web, con las capturas de pantalla: https://docs.cody-tech.com/academy/public-api/exportacion-de-datos

## 1. Descripción: Qué vas a lograr

Llevarte las conversaciones que ocurrieron en Cody, con el detalle que necesitas y sin pedirlas a nadie.

Cada vez que alguien de tu equipo platica con un agente de Cody queda una **conversación** (en la API se llama «thread»): sus mensajes, las respuestas del agente, cuánto tardó en responder, **la liga de la foto** que la persona haya enviado y, si la conversación nació de una misión de gamificación, a qué **misión** pertenece. La Public API te deja exportar todo eso con tres consultas, según el nivel de detalle que necesites:

- **Conversaciones completas.** `GET /data/threads`: cada conversación con su persona, su agente, su misión y todos sus mensajes con la respuesta del agente.
- **Mensaje por mensaje.** `GET /data/messages`: un renglón plano por cada mensaje de las personas, listo para una tabla. Incluye el correo de quien escribió.
- **Exportación sin correos.** `GET /data/messages/export`: los mismos renglones sin el correo, para compartir con quien no debe ver datos personales.
- **Fotos de la conversación.** Cuando una persona envía una foto, las tres consultas traen su liga pública en `media_url` (o `MediaUrl`). Detalle en [Las fotos que envía tu equipo](#imagenes).
- **Filtro por misión.** Las tres aceptan `challenge_id`: el identificador de una misión. Es la forma más directa de medir una campaña o una temporada.

**Flujo completo de una exportación con la Public API de Cody.** Un administrador crea la credencial en el AMS; tu proceso renueva su token, consulta las misiones para obtener el challenge_id, pide las conversaciones página por página y guarda el resultado en tu sistema.

```mermaid
sequenceDiagram
    autonumber
    participant ADMIN as Administrador
    participant SCRIPT as Tu proceso
    participant API as Public API
    participant STORE as Tu destino
    Note over ADMIN,STORE: 1 · Una sola vez
    ADMIN->>SCRIPT: Entrega Client ID, Client Secret y Refresh Token
    Note over ADMIN,STORE: 2 · Cada ejecución
    SCRIPT->>API: POST /auth/oauth/v2/refresh
    API-->>SCRIPT: access_token (vigente 1 hora)
    SCRIPT->>API: GET /gamification-challenge/list
    API-->>SCRIPT: Misiones con su id (challenge_id)
    Note over ADMIN,STORE: 3 · Descarga por páginas
    SCRIPT->>API: GET /data/threads?challenge_id=…&skip=0&limit=500
    API-->>SCRIPT: items + total
    SCRIPT->>API: Repite con skip=500, 1000… hasta reunir total
    SCRIPT-)STORE: Guarda los renglones (CSV, Excel, BI)
```

> **Todos los datos de esta guía son simulados.** La empresa «Grupo Aurora», sus personas, misiones e IDs no existen. Lo que sí es real es la forma: los nombres de los campos, sus tipos, el orden y el sobre de paginación son exactamente los que entrega la Public API.

## 2. Antes de empezar: Lo que necesitas

Revisa esta lista antes de escribir la primera línea: si falta una pieza, la exportación regresa vacía o con error.

- **Una credencial de servicio.** Un administrador la crea en el AMS, en **Infraestructura → Integraciones API**. El paso a paso está en la guía [Credenciales para la Public API](https://docs.cody-tech.com/academy/ams/credenciales-public-api).
- **Que actúe como administrador.** La credencial ve lo que ve la persona que eligieron al crearla. Para exportar las conversaciones de toda tu organización, pide que actúe como un administrador.
- **Un lugar seguro para correr.** Un servidor, un proceso programado o una herramienta de automatización. Nunca desde una página web ni una app: las credenciales son secretas.
- **La URL base.** Todas las rutas de esta guía se escriben después de `https://api.public.cody-tech.com`.

> **Lo que exportas incluye datos personales.** `/data/threads` y `/data/messages` traen el nombre y el correo de las personas. Guárdalos con el mismo cuidado que cualquier dato personal y, si el archivo va a circular fuera de tu equipo, usa `/data/messages/export`, que no incluye correos (las ligas de las fotos sí viajan, ver [Las fotos que envía tu equipo](#imagenes)).

## 3. Credencial y token: Consigue tu access token

La credencial se crea una vez; el token se renueva cada hora sin intervención de nadie.

### Paso 1. Pide la credencial a un administrador

En el AMS, un administrador abre **Infraestructura → Integraciones API**, hace clic en **Nueva credencial**, le pone un nombre como «Exportación de datos BI», elige en nombre de qué persona actuará y copia los cuatro valores que aparecen. El recorrido completo, con capturas, está en [Credenciales para la Public API](https://docs.cody-tech.com/academy/ams/credenciales-public-api).

![Mensaje Credencial creada exitosamente con el aviso «Guárdalas ahora — no podrás verlas después» y los campos Client ID, Client Secret, Access Token y Refresh Token, cada uno con botón para copiar.](https://docs.cody-tech.com/screenshots/ams/credenciales-public-api-creada.png)

*Los cuatro valores aparecen una sola vez, al crear la credencial. Datos de ejemplo.*

### Paso 2. Guárdala en variables de entorno

Guarda los valores en el gestor de secretos de tu equipo o en variables de entorno del servidor que va a correr la exportación. Nunca en el código ni en un repositorio.

```
# URL base de la Public API de Cody.
CODY_API_URL="https://api.public.cody-tech.com"

# Valores entregados al crear la credencial de servicio en Cody AMS.
# Guárdalos en tu gestor de secretos; nunca en el código fuente.
CODY_CLIENT_ID="<client-id>"
CODY_CLIENT_SECRET="<client-secret>"
CODY_REFRESH_TOKEN="<refresh-token>"
CODY_ACCESS_TOKEN="<access-token>"   # vigente por 1 hora
```

### Paso 3. Renueva el access token

El access token vence a la hora. Al empezar cada exportación, pide uno nuevo con tu Client ID, tu Client Secret y tu Refresh Token. El refresh token no cambia: consérvalo.

**Solicitud**

##### cURL

```
curl -X POST "$CODY_API_URL/auth/oauth/v2/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "'"$CODY_CLIENT_ID"'",
    "client_secret": "'"$CODY_CLIENT_SECRET"'",
    "refresh_token": "'"$CODY_REFRESH_TOKEN"'"
  }'
```

##### JavaScript

```
const response = await fetch(`${process.env.CODY_API_URL}/auth/oauth/v2/refresh`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: process.env.CODY_CLIENT_ID,
    client_secret: process.env.CODY_CLIENT_SECRET,
    refresh_token: process.env.CODY_REFRESH_TOKEN,
  }),
})
const { access_token, expires_in } = await response.json()
```

##### Python

```
import os
import requests

response = requests.post(
    f"{os.environ['CODY_API_URL']}/auth/oauth/v2/refresh",
    json={
        "client_id": os.environ["CODY_CLIENT_ID"],
        "client_secret": os.environ["CODY_CLIENT_SECRET"],
        "refresh_token": os.environ["CODY_REFRESH_TOKEN"],
    },
    timeout=30,
)
response.raise_for_status()
access_token = response.json()["access_token"]
```

```
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Cada consulta de esta guía lleva ese token en el encabezado `Authorization`:

```
Authorization: Bearer <access_token>
Content-Type: application/json
```

> **Si una consulta responde 401.** El token venció a media descarga. Renueva y reintenta esa misma página **una sola vez**; no empieces la exportación desde cero.

## 4. IDs: Encuentra los IDs para filtrar

Los filtros trabajan con identificadores, no con nombres. Así obtienes cada uno.

### Paso 1. Misiones: el challenge_id

Cada misión de gamificación tiene un `id`: ese es el `challenge_id` que usarás para filtrar. Lista las misiones de tu organización y quédate con el `id` de la que te interesa. Puedes acotar con `status` (`active`, `locked` o `completed`) o con `season_id` para ver solo las de una temporada.

**Solicitud**

##### cURL

```
curl "$CODY_API_URL/gamification-challenge/list?status=active&limit=100" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### JavaScript

```
const response = await fetch(
  `${process.env.CODY_API_URL}/gamification-challenge/list?status=active&limit=100`,
  { headers: { Authorization: `Bearer ${accessToken}` } },
)
const challenges = await response.json()

// Nombre de la misión → challenge_id, para filtrar la exportación
const challengeIdByName = new Map(challenges.map((challenge) => [challenge.name, challenge.id]))
```

##### Python

```
response = requests.get(
    f"{CODY_API_URL}/gamification-challenge/list",
    params={"status": "active", "limit": 100},
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=30,
)
response.raise_for_status()
challenges = response.json()

# Nombre de la misión → challenge_id, para filtrar la exportación
challenge_id_by_name = {challenge["name"]: challenge["id"] for challenge in challenges}
```

```json
[
  {
    "id": "6710f3a2c4b5d6e7f8091a2b",
    "season_id": "6710e1b0a1b2c3d4e5f60718",
    "name": "Venta cruzada del día",
    "goal": "5",
    "description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron.",
    "agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
    "agent_context_action": "Pregunta cuántas ventas cruzadas hizo la persona y regístralas.",
    "difficulty": "medium",
    "status": "active",
    "stored_status": "active",
    "effective_status": "active",
    "schedule_open": true,
    "schedule": {
      "type": "daily",
      "timezone": "America/Mexico_City",
      "start_time": "09:00",
      "end_time": "21:00",
      "start_date": "2026-10-01",
      "end_date": "2026-12-31",
      "days_of_week": [],
      "day_of_month": null,
      "day_of_month_range_start": null,
      "day_of_month_range_end": null
    },
    "display_order": 0,
    "orgchart_element_ids": [
      "66c0d1e2f3a4b5c6d7e8f901"
    ]
  },
  {
    "id": "6710f3a2c4b5d6e7f8091a2c",
    "season_id": "6710e1b0a1b2c3d4e5f60718",
    "name": "Recomienda el producto del mes",
    "goal": "10",
    "description": "Recomienda el producto del mes en cada venta y registra cuántas veces lo ofreciste.",
    "agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
    "agent_context_action": "",
    "difficulty": "easy",
    "status": "active",
    "stored_status": "active",
    "effective_status": "active",
    "schedule_open": true,
    "schedule": null,
    "display_order": 1,
    "orgchart_element_ids": []
  }
]
```

| Campo | Qué contiene |
| --- | --- |
| `id` | El identificador de la misión. Es el valor de `challenge_id` en los filtros. |
| `name` / `description` | Nombre y descripción vigentes de la misión. |
| `season_id` | La temporada a la que pertenece. |
| `agent_id` | El agente que acompaña la misión, si tiene uno. Sirve como filtro `agent_id`. |
| `status` | `active`, `locked` o `completed`, ya considerando su horario. |
| `schedule` | Cuándo está abierta la misión (tipo, zona horaria, horas y fechas), o `null` si no tiene horario. |

> **La respuesta es una lista directa.** A diferencia de las consultas de datos, `/gamification-challenge/list` responde un arreglo, sin `total`. Pide de 100 en 100 (hasta 1,000) con `skip` y `limit` hasta que llegue una lista vacía.

### Paso 2. Personas: los user_ids

Para exportar solo a ciertas personas, necesitas su ID de usuario en Cody. Lista los usuarios y arma una tabla de equivalencias con el correo, que es lo que normalmente tienes en tus sistemas.

**Solicitud**

##### cURL

```
curl "$CODY_API_URL/user/list?skip=0&limit=1000" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### JavaScript

```
const response = await fetch(`${process.env.CODY_API_URL}/user/list?skip=0&limit=1000`, {
  headers: { Authorization: `Bearer ${accessToken}` },
})
const users = await response.json()

// Correo → ID de usuario en Cody, para armar el filtro user_ids
const codyIdByEmail = new Map(users.map((user) => [user.email.toLowerCase(), user.id]))
```

##### Python

```
response = requests.get(
    f"{CODY_API_URL}/user/list",
    params={"skip": 0, "limit": 1000},
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=30,
)
response.raise_for_status()
users = response.json()

# Correo → ID de usuario en Cody, para armar el filtro user_ids
cody_id_by_email = {user["email"].lower(): user["id"] for user in users}
```

```json
[
  {
    "id": "664f5f3c2f4f5e3b1c2a9d10",
    "name": "Ana",
    "lastname": "Torres Vega",
    "username": "ana.torres",
    "email": "ana.torres@ejemplo.com"
  },
  {
    "id": "664f5f3c2f4f5e3b1c2a9d11",
    "name": "Diego",
    "lastname": "Ramírez Peña",
    "username": "diego.ramirez",
    "email": "diego.ramirez@ejemplo.com"
  },
  {
    "id": "664f5f3c2f4f5e3b1c2a9d12",
    "name": "Fernanda",
    "lastname": "Castillo Ruiz",
    "username": "fernanda.castillo",
    "email": "fernanda.castillo@ejemplo.com"
  }
]
```

### Paso 3. Agentes y conversaciones: agent_id y thread_id

- **`agent_id`:** viene en cada misión (`agent_id`) y en cada conversación exportada (`agent.agent_id`). También lo ves en el AMS: al abrir un agente en **Mis Agentes → Todos los Agentes**, es la última parte de la dirección de la página (`/assistants/<agent_id>`).
- **`thread_id`:** viene en cada conversación (`thread_id`) y en cada renglón de mensajes (`ThreadId`). Úsalo para volver a pedir una conversación completa.

## 5. Qué exportar: Elige la consulta adecuada

Las tres comparten autenticación, paginación y el filtro por misión; cambian en el detalle que entregan.

| Consulta | Un elemento es… | Trae la respuesta del agente | Trae el correo | Ideal para |
| --- | --- | --- | --- | --- |
| `GET /data/threads` | Una conversación con todos sus mensajes | Sí (`answer`) | Sí (`user.email`) | Análisis de calidad, auditoría y reportes por misión. |
| `GET /data/messages` | Un mensaje de una persona | No, solo el tiempo de respuesta | Sí (`UserEmail`) | Tablas de actividad y conteos por día o por persona. |
| `GET /data/messages/export` | Un mensaje de una persona | No, solo el tiempo de respuesta | No | Archivos que se comparten fuera del equipo. |

| Campo | Tipo | Qué contiene |
| --- | --- | --- |
| `thread_id` | texto | ID de la conversación. |
| `challenge_id` | texto o null | La misión de la que nació la conversación, si tiene una. |
| `challenge` | objeto o null | `challenge_id`, `name` y `description` vigentes de la misión; `null` si no tiene o ya no existe. |
| `topic` | texto o null | El nombre de la misión si tiene una; si no, el título de la conversación. |
| `thread_title` / `thread_summary` | texto o null | Título y resumen que Cody genera de la conversación. |
| `test_mode` | sí / no | `true` si fue una conversación de prueba (solo aparecen si las pides). |
| `created_at` / `updated_at` | fecha y hora | Inicio y última actividad, en hora UTC. |
| `custom_metadata` | objeto o null | Datos adicionales de la conversación, como su `challenge_id`. |
| `user` | objeto | `user_id`, `name`, `lastname` y `email` de la persona. |
| `agent` | objeto o null | `agent_id` y `name` del agente. |
| `message_count` | número | Cuántos mensajes tiene, aunque no pidas su contenido. |
| `messages` | lista | Cada mensaje: `message_id`, `message` (lo que escribió la persona), `answer` (la respuesta del agente), `answer_time` (segundos), `created_at`, `custom_metadata` y `media_url` (la liga de la foto que envió la persona, o `null`). |

| Campo | Qué contiene |
| --- | --- |
| `MessageDate` / `MessageTime` | Fecha (`AAAA-MM-DD`) y hora (`HH:MM:SS`) del mensaje, en UTC. |
| `MessageID` | ID del mensaje. |
| `ResponseTime` | Segundos que tardó el agente en responder, o `null`. |
| `UserID` | ID de la persona que escribió. |
| `UserEmail` | Su correo. **No viene en `/data/messages/export`.** |
| `ThreadId` | ID de la conversación a la que pertenece. |
| `Message` | Lo que escribió la persona. |
| `MediaUrl` | La liga pública de la foto que envió la persona en ese mensaje, o `null` si no envió ninguna. |
| `Topic` | El nombre de la misión si la conversación tiene una; si no, el título de la conversación. |
| `ChallengeId` | El `challenge_id` de la conversación, o `null`. |

> **Solo ves los datos de tu organización.** La credencial queda fijada a tu organización: aunque envíes otro `tenant_id`, la Public API lo ignora y solo te entrega tus propias conversaciones.

## 6. Fotos: Las fotos que envía tu equipo

Cuando alguien comparte una foto con un agente, su liga viaja en la exportación, junto al mensaje en que la envió.

Una persona puede enviarle una foto al agente, por ejemplo en un paso **Pregunta con foto** de un flujo de Workflow Studio (consulta [Automatiza procesos con Workflow Studio](https://docs.cody-tech.com/academy/ams/workflow-studio)). Cody guarda la imagen y la deja ligada al mensaje en que se envió. Al exportar, ese mensaje trae la **liga pública** de la foto: no tienes que pedirla aparte.

| Consulta | Campo | Dónde |
| --- | --- | --- |
| `GET /data/threads` | `media_url` | Dentro de cada elemento de `messages`. |
| `GET /data/messages` | `MediaUrl` | En el renglón del mensaje. |
| `GET /data/messages/export` | `MediaUrl` | En el renglón del mensaje. Quitar el correo no quita la liga de la foto. |

El mensaje con foto trae la liga; los demás traen el mismo campo en `null`:

##### Mensaje con foto en /data/threads (simulado)

```json
{
  "message_id": "6719b8e4a1c2d3e4f5a6b7c9",
  "message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
  "answer": "Se ve ordenada y las pantallas de 55 y 65 pulgadas quedan a la altura de los ojos. Pon el letrero de la barra de sonido junto a los soportes para que se vea el complemento.",
  "answer_time": 4.37,
  "created_at": "2026-10-21T19:12:40.115000",
  "custom_metadata": null,
  "media_url": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg"
}
```

##### Renglón con foto en /data/messages (simulado)

```json
{
  "MessageDate": "2026-10-21",
  "MessageTime": "19:12:40",
  "MessageID": "6719b8e4a1c2d3e4f5a6b7c9",
  "ResponseTime": 4.37,
  "UserID": "664f5f3c2f4f5e3b1c2a9d10",
  "UserEmail": "ana.torres@ejemplo.com",
  "ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
  "Message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
  "MediaUrl": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg",
  "Topic": "Venta cruzada del día",
  "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
}
```

- **El campo siempre está presente.** Un mensaje sin foto trae `null`, así que tu proceso no necesita tratar el campo como opcional.
- **Mensajes anteriores a esta función no traen liga**, aunque en su momento hayan llevado una foto.
- **No hay un filtro para pedir solo los mensajes con foto.** Descarga con los filtros de siempre y quédate con los renglones cuya liga no sea `null`.
- **La liga abre la imagen directamente**, sin el token de la Public API.

> **Quien tenga la liga puede ver la foto.** La liga es pública: se abre sin iniciar sesión. Las fotos pueden mostrar personas, tiendas o documentos, así que trátala con el mismo cuidado que un dato personal y no la publiques. Si compartes un archivo exportado fuera de tu equipo, recuerda que `/data/messages/export` quita los correos pero **conserva** las ligas de las fotos.

Si necesitas guardar las fotos en tu propio almacenamiento, recorre los renglones y descarga cada liga:

**Descargar las fotos**

##### cURL

```
# La liga de la imagen es pública: no necesita el token de la Public API
curl -L -o exhibicion-pantallas.jpg   "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg"
```

##### Python

```
import os
from urllib.parse import urlparse

import requests


def download_images(rows: list[dict], folder: str = "imagenes") -> None:
    """Guarda cada foto de los renglones que tienen url_imagen."""
    os.makedirs(folder, exist_ok=True)
    for row in rows:
        url = row.get("url_imagen")
        if not url:
            continue  # mensaje sin foto
        # Prefijo con la conversación para que dos fotos con el mismo nombre no se pisen
        name = f"{row['conversacion']}_{os.path.basename(urlparse(url).path)}"
        response = requests.get(url, timeout=60)
        response.raise_for_status()
        with open(os.path.join(folder, name), "wb") as file:
            file.write(response.content)


download_images(to_rows(threads))
```

> **¿Prefieres verlas sin código?.** En el AMS, al abrir una conversación en la pestaña **Observabilidad** de un agente, la foto aparece en el mensaje de quien la envió, y la descarga de conversaciones, en CSV o en JSON, incluye la liga en `media_url`. El recorrido está en la guía [Ajusta y supervisa a tus agentes](https://docs.cody-tech.com/academy/ams/agentes).

## 7. Filtros: Todos los filtros, de un vistazo

Combínalos como necesites: cada filtro que agregas acota el resultado.

| Filtro | Formato | Qué hace |
| --- | --- | --- |
| `challenge_id` | ID de misión | Solo conversaciones de esa misión. Sin él, entran todas, tengan misión o no. |
| `date_from` / `date_to` | `AAAA-MM-DD` | Por día de inicio de la conversación, **ambos días incluidos**. |
| `created_from` / `created_to` | Fecha y hora ISO, ej. `2026-10-21T14:00:00Z` | Por momento exacto de inicio, ambos incluidos. Si los envías, mandan sobre `date_from` / `date_to`. |
| `user_ids` | IDs separados por comas | Solo conversaciones de esas personas. **Máximo 100** por consulta. |
| `agent_id` | ID de agente | Solo conversaciones con ese agente. |
| `thread_id` | ID de conversación | Solo esa conversación. |
| `search` | Texto (hasta 100 caracteres) | Busca en el título y el resumen de la conversación, sin distinguir mayúsculas. |
| `include_messages` | `true` / `false` | `true` (por omisión) trae los mensajes; `false` trae solo la conversación y `message_count`. |
| `include_test_mode` | `true` / `false` | `false` (por omisión) deja fuera las conversaciones de prueba. |
| `skip` / `limit` | Números | Paginación: `limit` va de 1 a 500 (100 por omisión). |

| Filtro | Formato | Qué hace |
| --- | --- | --- |
| `challenge_id` | ID de misión | Solo mensajes de conversaciones de esa misión. |
| `start` / `end` | Fecha y hora ISO, ej. `2026-10-01T00:00:00Z` | Por momento del mensaje. `start` debe ser anterior a `end`. |
| `include_test_mode` | `true` / `false` | `false` (por omisión) deja fuera los mensajes de conversaciones de prueba. |
| `skip` / `limit` | Números | Paginación: `limit` va de 1 a 500 (100 por omisión). |

> **Ojo con el periodo por omisión: 30 días.** `/data/messages` y `/data/messages/export` **siempre** se limitan a los últimos 30 días si no envías `start`, aunque filtres por misión. `/data/threads` solo lo hace cuando no envías ni `challenge_id`, ni `thread_id`, ni `date_from`, ni `created_from`: con `challenge_id` te entrega todo el historial de la misión.

> **Todas las fechas son UTC.** Las fechas que envías y las que recibes están en hora UTC. En el centro de México son 6 horas más que la hora local: las 9:00 de la mañana en Ciudad de México son las `15:00:00Z`.

## 8. Por misión: Ejemplo: todas las conversaciones de una misión

El caso más común: medir una misión de principio a fin.

Con solo el `challenge_id` recibes todas las conversaciones de la misión, de la más reciente a la más antigua, cada una con sus mensajes en orden de llegada.

**Solicitud**

##### cURL

```
curl -G "$CODY_API_URL/data/threads" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
  --data-urlencode "limit=100"
```

##### JavaScript

```
const params = new URLSearchParams({
  challenge_id: "6710f3a2c4b5d6e7f8091a2b",
  limit: "100",
})
const response = await fetch(`${process.env.CODY_API_URL}/data/threads?${params}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
})
const { items, total } = await response.json()
console.log(`${items.length} de ${total} conversaciones de la misión`)
```

##### Python

```
response = requests.get(
    f"{CODY_API_URL}/data/threads",
    params={"challenge_id": "6710f3a2c4b5d6e7f8091a2b", "limit": 100},
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=60,
)
response.raise_for_status()
page = response.json()
print(f"{len(page['items'])} de {page['total']} conversaciones de la misión")
```

```json
{
  "items": [
    {
      "thread_id": "6719a0c1b2d3e4f5a6b7c8d9",
      "tenant_id": "66a1b2c3d4e5f60718293a4b",
      "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
      "challenge": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
        "name": "Venta cruzada del día",
        "description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
      },
      "thread_title": "Complementos para pantallas",
      "topic": "Venta cruzada del día",
      "thread_summary": "Ana pidió ideas de complementos para clientes que compran pantallas y reportó 4 ventas cruzadas al cierre del turno.",
      "test_mode": false,
      "created_at": "2026-10-21T15:04:12.318000",
      "updated_at": "2026-10-21T22:41:07.902000",
      "custom_metadata": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b"
      },
      "user": {
        "user_id": "664f5f3c2f4f5e3b1c2a9d10",
        "name": "Ana",
        "lastname": "Torres Vega",
        "email": "ana.torres@ejemplo.com"
      },
      "agent": {
        "agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
        "name": "Coach Comercial"
      },
      "message_count": 3,
      "messages": [
        {
          "message_id": "6719a0c5e1f2a3b4c5d6e7f8",
          "message": "¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?",
          "answer": "Tres opciones que suelen funcionar: un soporte de pared, una barra de sonido y la garantía extendida. Empieza por el soporte: casi todos lo necesitan y lo aceptan más fácil.",
          "answer_time": 2.84,
          "created_at": "2026-10-21T15:04:12.318000",
          "custom_metadata": null,
          "media_url": null
        },
        {
          "message_id": "6719b8e4a1c2d3e4f5a6b7c9",
          "message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
          "answer": "Se ve ordenada y las pantallas de 55 y 65 pulgadas quedan a la altura de los ojos. Pon el letrero de la barra de sonido junto a los soportes para que se vea el complemento.",
          "answer_time": 4.37,
          "created_at": "2026-10-21T19:12:40.115000",
          "custom_metadata": null,
          "media_url": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg"
        },
        {
          "message_id": "6719d2f0a9b8c7d6e5f4a3b2",
          "message": "Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.",
          "answer": "¡Excelente cierre, Ana! Ya registré tus 4 ventas cruzadas en la misión de hoy. Mañana prueba ofrecer la barra de sonido primero a quien compre pantallas de 65 pulgadas.",
          "answer_time": 3.12,
          "created_at": "2026-10-21T22:41:07.902000",
          "custom_metadata": null,
          "media_url": null
        }
      ]
    },
    {
      "thread_id": "6719a0c1b2d3e4f5a6b7c8da",
      "tenant_id": "66a1b2c3d4e5f60718293a4b",
      "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
      "challenge": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
        "name": "Venta cruzada del día",
        "description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
      },
      "thread_title": "Complementos para celulares",
      "topic": "Venta cruzada del día",
      "thread_summary": "Diego preguntó qué ofrecer con un celular de gama media y registró 2 ventas de fundas con mica.",
      "test_mode": false,
      "created_at": "2026-10-20T17:22:45.051000",
      "updated_at": "2026-10-20T17:30:18.664000",
      "custom_metadata": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b"
      },
      "user": {
        "user_id": "664f5f3c2f4f5e3b1c2a9d11",
        "name": "Diego",
        "lastname": "Ramírez Peña",
        "email": "diego.ramirez@ejemplo.com"
      },
      "agent": {
        "agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
        "name": "Coach Comercial"
      },
      "message_count": 2,
      "messages": [
        {
          "message_id": "6718f1b5c4d3e2f1a0b9c8d7",
          "message": "Un cliente se lleva un celular de gama media, ¿qué le ofrezco?",
          "answer": "Funda con mica incluida: protege la compra y es el complemento que más se acepta en esa gama.",
          "answer_time": 1.97,
          "created_at": "2026-10-20T17:22:45.051000",
          "custom_metadata": null,
          "media_url": null
        },
        {
          "message_id": "6718f3a2b1c0d9e8f7a6b5c4",
          "message": "Listo, vendí 2 fundas con mica.",
          "answer": "¡Bien hecho, Diego! Registré 2 ventas cruzadas en tu misión de hoy.",
          "answer_time": 1.45,
          "created_at": "2026-10-20T17:30:18.664000",
          "custom_metadata": null,
          "media_url": null
        }
      ]
    }
  ],
  "total": 2,
  "skip": 0,
  "limit": 100
}
```

- `total` es el número de conversaciones que cumplen el filtro, no el tamaño de esta página. Te dice cuántas páginas faltan.
- `topic` y `challenge.name` muestran el nombre **actual** de la misión, aunque haya cambiado después de la conversación.
- Dentro de cada conversación, `message` es lo que escribió la persona y `answer`, lo que respondió el agente.

## 9. Por fechas: Ejemplo: una misión en un periodo

Por días completos o con hora exacta.

### Paso 1. Por días completos: date_from y date_to

Úsalos para cortes de mes, de semana o de temporada. `date_to` incluye todo ese día.

##### cURL

```
# Conversaciones de la misión creadas entre el 1 y el 31 de octubre (ambos días incluidos)
curl -G "$CODY_API_URL/data/threads" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
  --data-urlencode "date_from=2026-10-01" \
  --data-urlencode "date_to=2026-10-31"
```

##### JavaScript

```
const params = new URLSearchParams({
  challenge_id: "6710f3a2c4b5d6e7f8091a2b",
  date_from: "2026-10-01",
  date_to: "2026-10-31", // incluye todo el 31 de octubre
})
```

##### Python

```
params = {
    "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
    "date_from": "2026-10-01",
    "date_to": "2026-10-31",  # incluye todo el 31 de octubre
}
```

### Paso 2. Con hora exacta: created_from y created_to

Úsalos para turnos o para exportaciones incrementales (por ejemplo, «todo lo nuevo desde la última vez que corrí el proceso»). Ambos extremos están incluidos.

##### cURL

```
# Solo el turno de la tarde del 21 de octubre, en hora UTC
curl -G "$CODY_API_URL/data/threads" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
  --data-urlencode "created_from=2026-10-21T14:00:00Z" \
  --data-urlencode "created_to=2026-10-21T23:59:59Z"
```

##### JavaScript

```
const params = new URLSearchParams({
  challenge_id: "6710f3a2c4b5d6e7f8091a2b",
  created_from: "2026-10-21T14:00:00Z",
  created_to: "2026-10-21T23:59:59Z",
})
```

##### Python

```
params = {
    "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
    "created_from": "2026-10-21T14:00:00Z",
    "created_to": "2026-10-21T23:59:59Z",
}
```

> **Exportación incremental sin huecos.** Guarda el `created_at` más reciente que recibiste y úsalo como `created_from` en la siguiente ejecución. Como el extremo está incluido, puede repetirse una conversación: descártala por su `thread_id`.

## 10. Personas y agente: Ejemplo: personas, agente, texto y una conversación

Para enfocar la exportación en un equipo, un agente o un tema.

### Paso 1. Solo ciertas personas: user_ids

Envía los IDs en **un solo parámetro separado por comas**. Si repites `user_ids=…&user_ids=…`, solo se toma en cuenta el último. Para más de 100 personas, divide la lista y haz varias consultas.

##### cURL

```
# Varias personas: un solo parámetro con los IDs separados por comas (máximo 100)
curl -G "$CODY_API_URL/data/threads" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
  --data-urlencode "user_ids=664f5f3c2f4f5e3b1c2a9d10,664f5f3c2f4f5e3b1c2a9d11"
```

##### JavaScript

```
const userIds = ["664f5f3c2f4f5e3b1c2a9d10", "664f5f3c2f4f5e3b1c2a9d11"]
const params = new URLSearchParams({
  challenge_id: "6710f3a2c4b5d6e7f8091a2b",
  user_ids: userIds.join(","), // nunca repitas user_ids=…&user_ids=…
})
```

##### Python

```
user_ids = ["664f5f3c2f4f5e3b1c2a9d10", "664f5f3c2f4f5e3b1c2a9d11"]
params = {
    "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
    "user_ids": ",".join(user_ids),  # nunca una lista: un solo texto con comas
}
```

### Paso 2. Un agente y un tema: agent_id y search

##### cURL

```
# Conversaciones del agente Coach Comercial que mencionan "pantalla" en su título o resumen
curl -G "$CODY_API_URL/data/threads" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "agent_id=66b7c8d9e0f1a2b3c4d5e6f7" \
  --data-urlencode "search=pantalla" \
  --data-urlencode "date_from=2026-10-01"
```

##### JavaScript

```
const params = new URLSearchParams({
  agent_id: "66b7c8d9e0f1a2b3c4d5e6f7",
  search: "pantalla",
  date_from: "2026-10-01",
})
```

##### Python

```
params = {
    "agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
    "search": "pantalla",
    "date_from": "2026-10-01",
}
```

### Paso 3. Solo el resumen: include_messages=false

Cuando solo necesitas contar conversaciones o armar un tablero, pide la conversación sin el contenido de sus mensajes: la respuesta es mucho más ligera y `message_count` conserva el número real de mensajes.

**Solicitud**

```
# Solo el resumen de cada conversación: más ligero, ideal para contar o hacer un tablero
curl -G "$CODY_API_URL/data/threads" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
  --data-urlencode "include_messages=false"
```

```json
{
  "items": [
    {
      "thread_id": "6719a0c1b2d3e4f5a6b7c8d9",
      "tenant_id": "66a1b2c3d4e5f60718293a4b",
      "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
      "challenge": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
        "name": "Venta cruzada del día",
        "description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
      },
      "thread_title": "Complementos para pantallas",
      "topic": "Venta cruzada del día",
      "thread_summary": "Ana pidió ideas de complementos para clientes que compran pantallas y reportó 4 ventas cruzadas al cierre del turno.",
      "test_mode": false,
      "created_at": "2026-10-21T15:04:12.318000",
      "updated_at": "2026-10-21T22:41:07.902000",
      "custom_metadata": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b"
      },
      "user": {
        "user_id": "664f5f3c2f4f5e3b1c2a9d10",
        "name": "Ana",
        "lastname": "Torres Vega",
        "email": "ana.torres@ejemplo.com"
      },
      "agent": {
        "agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
        "name": "Coach Comercial"
      },
      "message_count": 3,
      "messages": []
    },
    {
      "thread_id": "6719a0c1b2d3e4f5a6b7c8da",
      "tenant_id": "66a1b2c3d4e5f60718293a4b",
      "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
      "challenge": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
        "name": "Venta cruzada del día",
        "description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
      },
      "thread_title": "Complementos para celulares",
      "topic": "Venta cruzada del día",
      "thread_summary": "Diego preguntó qué ofrecer con un celular de gama media y registró 2 ventas de fundas con mica.",
      "test_mode": false,
      "created_at": "2026-10-20T17:22:45.051000",
      "updated_at": "2026-10-20T17:30:18.664000",
      "custom_metadata": {
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b"
      },
      "user": {
        "user_id": "664f5f3c2f4f5e3b1c2a9d11",
        "name": "Diego",
        "lastname": "Ramírez Peña",
        "email": "diego.ramirez@ejemplo.com"
      },
      "agent": {
        "agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
        "name": "Coach Comercial"
      },
      "message_count": 2,
      "messages": []
    }
  ],
  "total": 2,
  "skip": 0,
  "limit": 100
}
```

### Paso 4. Una sola conversación: thread_id

```
# Una sola conversación, con todos sus mensajes
curl -G "$CODY_API_URL/data/threads" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "thread_id=6719a0c1b2d3e4f5a6b7c8d9"
```

## 11. Mensajes: Ejemplo: renglones de mensajes de una misión

Cuando quieres una tabla plana, sin armar nada.

### Paso 1. Con correo: /data/messages

Cada renglón es un mensaje que escribió una persona, del más reciente al más antiguo. Recuerda enviar `start`: sin él, solo recibes los últimos 30 días.

**Solicitud**

##### cURL

```
# Un renglón por mensaje de las personas en la misión, durante octubre (hora UTC)
curl -G "$CODY_API_URL/data/messages" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
  --data-urlencode "start=2026-10-01T00:00:00Z" \
  --data-urlencode "end=2026-10-31T23:59:59Z" \
  --data-urlencode "limit=500"
```

##### JavaScript

```
const params = new URLSearchParams({
  challenge_id: "6710f3a2c4b5d6e7f8091a2b",
  start: "2026-10-01T00:00:00Z",
  end: "2026-10-31T23:59:59Z",
  limit: "500",
})
const response = await fetch(`${process.env.CODY_API_URL}/data/messages?${params}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
})
const { conversations, total } = await response.json()
```

##### Python

```
response = requests.get(
    f"{CODY_API_URL}/data/messages",
    params={
        "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
        "start": "2026-10-01T00:00:00Z",
        "end": "2026-10-31T23:59:59Z",
        "limit": 500,
    },
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=60,
)
response.raise_for_status()
rows = response.json()["conversations"]
```

```json
{
  "conversations": [
    {
      "MessageDate": "2026-10-21",
      "MessageTime": "22:41:07",
      "MessageID": "6719d2f0a9b8c7d6e5f4a3b2",
      "ResponseTime": 3.12,
      "UserID": "664f5f3c2f4f5e3b1c2a9d10",
      "UserEmail": "ana.torres@ejemplo.com",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
      "Message": "Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.",
      "MediaUrl": null,
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    },
    {
      "MessageDate": "2026-10-21",
      "MessageTime": "19:12:40",
      "MessageID": "6719b8e4a1c2d3e4f5a6b7c9",
      "ResponseTime": 4.37,
      "UserID": "664f5f3c2f4f5e3b1c2a9d10",
      "UserEmail": "ana.torres@ejemplo.com",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
      "Message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
      "MediaUrl": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg",
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    },
    {
      "MessageDate": "2026-10-21",
      "MessageTime": "15:04:12",
      "MessageID": "6719a0c5e1f2a3b4c5d6e7f8",
      "ResponseTime": 2.84,
      "UserID": "664f5f3c2f4f5e3b1c2a9d10",
      "UserEmail": "ana.torres@ejemplo.com",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
      "Message": "¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?",
      "MediaUrl": null,
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    },
    {
      "MessageDate": "2026-10-20",
      "MessageTime": "17:30:18",
      "MessageID": "6718f3a2b1c0d9e8f7a6b5c4",
      "ResponseTime": 1.45,
      "UserID": "664f5f3c2f4f5e3b1c2a9d11",
      "UserEmail": "diego.ramirez@ejemplo.com",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8da",
      "Message": "Listo, vendí 2 fundas con mica.",
      "MediaUrl": null,
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    }
  ],
  "total": 4,
  "skip": 0,
  "limit": 500
}
```

### Paso 2. Sin correo: /data/messages/export

Los mismos filtros y los mismos renglones, sin `UserEmail`. Es la opción para archivos que van a circular fuera de tu equipo.

**Solicitud**

```
# Mismos filtros que /data/messages, sin el correo de las personas
curl -G "$CODY_API_URL/data/messages/export" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  --data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
  --data-urlencode "start=2026-10-01T00:00:00Z" \
  --data-urlencode "end=2026-10-31T23:59:59Z" \
  --data-urlencode "limit=500"
```

```json
{
  "conversations": [
    {
      "MessageDate": "2026-10-21",
      "MessageTime": "22:41:07",
      "MessageID": "6719d2f0a9b8c7d6e5f4a3b2",
      "ResponseTime": 3.12,
      "UserID": "664f5f3c2f4f5e3b1c2a9d10",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
      "Message": "Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.",
      "MediaUrl": null,
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    },
    {
      "MessageDate": "2026-10-21",
      "MessageTime": "19:12:40",
      "MessageID": "6719b8e4a1c2d3e4f5a6b7c9",
      "ResponseTime": 4.37,
      "UserID": "664f5f3c2f4f5e3b1c2a9d10",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
      "Message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
      "MediaUrl": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg",
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    },
    {
      "MessageDate": "2026-10-21",
      "MessageTime": "15:04:12",
      "MessageID": "6719a0c5e1f2a3b4c5d6e7f8",
      "ResponseTime": 2.84,
      "UserID": "664f5f3c2f4f5e3b1c2a9d10",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
      "Message": "¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?",
      "MediaUrl": null,
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    },
    {
      "MessageDate": "2026-10-20",
      "MessageTime": "17:30:18",
      "MessageID": "6718f3a2b1c0d9e8f7a6b5c4",
      "ResponseTime": 1.45,
      "UserID": "664f5f3c2f4f5e3b1c2a9d11",
      "ThreadId": "6719a0c1b2d3e4f5a6b7c8da",
      "Message": "Listo, vendí 2 fundas con mica.",
      "MediaUrl": null,
      "Topic": "Venta cruzada del día",
      "ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
    }
  ],
  "total": 4,
  "skip": 0,
  "limit": 500
}
```

## 12. Descarga completa: Descarga todo y conviértelo a CSV

Las consultas entregan páginas de hasta 500 elementos. Pide página tras página hasta reunir el total.

1. Pide la primera página con `skip=0` y `limit=500`.
2. Lee `total`: es cuántos elementos cumplen el filtro.
3. Suma 500 a `skip` y pide la siguiente página.
4. Detente cuando `skip` alcance `total` o cuando una página llegue vacía.

Este script hace todo el recorrido para una misión: renueva el token, descarga todas las páginas de `/data/threads` y escribe un CSV con un renglón por mensaje, los datos de su conversación al lado y, cuando el mensaje tiene foto, su liga en `url_imagen`.

**exportar_mision**

##### Python

```
"""Descarga todas las conversaciones de una misión y las guarda en un CSV.

Uso:  python exportar_mision.py 6710f3a2c4b5d6e7f8091a2b
Requiere: pip install requests
"""
import csv
import os
import sys

import requests

CODY_API_URL = os.environ["CODY_API_URL"]
PAGE_SIZE = 500  # el máximo que acepta la Public API


def get_access_token() -> str:
    """Renueva el access token con la credencial de servicio."""
    response = requests.post(
        f"{CODY_API_URL}/auth/oauth/v2/refresh",
        json={
            "client_id": os.environ["CODY_CLIENT_ID"],
            "client_secret": os.environ["CODY_CLIENT_SECRET"],
            "refresh_token": os.environ["CODY_REFRESH_TOKEN"],
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["access_token"]


def fetch_all_threads(token: str, filters: dict) -> list[dict]:
    """Pide páginas de 500 hasta reunir el total que reporta la API."""
    threads, skip = [], 0
    while True:
        response = requests.get(
            f"{CODY_API_URL}/data/threads",
            params={**filters, "skip": skip, "limit": PAGE_SIZE},
            headers={"Authorization": f"Bearer {token}"},
            timeout=120,
        )
        response.raise_for_status()
        page = response.json()
        threads.extend(page["items"])
        skip += PAGE_SIZE
        if not page["items"] or skip >= page["total"]:
            return threads


def to_rows(threads: list[dict]) -> list[dict]:
    """Un renglón por mensaje, con los datos de su conversación al lado."""
    rows = []
    for thread in threads:
        user = thread["user"] or {}
        agent = thread["agent"] or {}
        for message in thread["messages"]:
            rows.append({
                "fecha_utc": message["created_at"],
                "mision": thread["topic"],
                "challenge_id": thread["challenge_id"],
                "persona": f"{user.get('name') or ''} {user.get('lastname') or ''}".strip(),
                "correo": user.get("email"),
                "agente": agent.get("name"),
                "conversacion": thread["thread_id"],
                "pregunta": message["message"],
                "respuesta": message["answer"],
                "segundos_respuesta": message["answer_time"],
                "url_imagen": message.get("media_url"),  # vacío si el mensaje no tiene foto
            })
    return rows


if __name__ == "__main__":
    challenge_id = sys.argv[1]
    token = get_access_token()
    threads = fetch_all_threads(token, {"challenge_id": challenge_id})
    rows = to_rows(threads)

    # utf-8-sig: Excel abre acentos y eñes sin configurar nada
    with open(f"mision_{challenge_id}.csv", "w", newline="", encoding="utf-8-sig") as file:
        writer = csv.DictWriter(file, fieldnames=list(rows[0]) if rows else ["fecha_utc"])
        writer.writeheader()
        writer.writerows(rows)

    print(f"{len(threads)} conversaciones, {len(rows)} mensajes exportados")
```

##### JavaScript

```
// Descarga todas las conversaciones de una misión y las guarda en un CSV.
// Uso:  node exportar-mision.mjs 6710f3a2c4b5d6e7f8091a2b   (Node 18 o superior)
import { writeFile } from "node:fs/promises"

const API = process.env.CODY_API_URL
const PAGE_SIZE = 500 // el máximo que acepta la Public API

async function getAccessToken() {
  const response = await fetch(`${API}/auth/oauth/v2/refresh`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: process.env.CODY_CLIENT_ID,
      client_secret: process.env.CODY_CLIENT_SECRET,
      refresh_token: process.env.CODY_REFRESH_TOKEN,
    }),
  })
  if (!response.ok) throw new Error(`No se pudo renovar el token: ${response.status}`)
  return (await response.json()).access_token
}

async function fetchAllThreads(token, filters) {
  const threads = []
  for (let skip = 0; ; skip += PAGE_SIZE) {
    const params = new URLSearchParams({ ...filters, skip: String(skip), limit: String(PAGE_SIZE) })
    const response = await fetch(`${API}/data/threads?${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    })
    if (!response.ok) throw new Error(`Error ${response.status}: ${await response.text()}`)
    const page = await response.json()
    threads.push(...page.items)
    if (page.items.length === 0 || skip + PAGE_SIZE >= page.total) return threads
  }
}

const csvCell = (value) => `"${String(value ?? "").replaceAll('"', '""')}"`

const challengeId = process.argv[2]
const token = await getAccessToken()
const threads = await fetchAllThreads(token, { challenge_id: challengeId })

const header = ["fecha_utc", "mision", "challenge_id", "persona", "correo", "agente", "conversacion", "pregunta", "respuesta", "segundos_respuesta", "url_imagen"]
const lines = [header.join(",")]
for (const thread of threads) {
  const person = `${thread.user?.name ?? ""} ${thread.user?.lastname ?? ""}`.trim()
  for (const message of thread.messages) {
    lines.push([
      message.created_at, thread.topic, thread.challenge_id, person, thread.user?.email,
      thread.agent?.name, thread.thread_id, message.message, message.answer, message.answer_time,
      message.media_url, // vacío si el mensaje no tiene foto
    ].map(csvCell).join(","))
  }
}

// El BOM (\uFEFF) hace que Excel reconozca acentos y eñes al abrir el archivo
await writeFile(`mision_${challengeId}.csv`, "\uFEFF" + lines.join("\n"), "utf8")
console.log(`${threads.length} conversaciones, ${lines.length - 1} mensajes exportados`)
```

**Resultado**

```csv
fecha_utc,mision,challenge_id,persona,correo,agente,conversacion,pregunta,respuesta,segundos_respuesta,url_imagen
2026-10-21T15:04:12.318000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Ana Torres Vega,ana.torres@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8d9,¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?,"Tres opciones que suelen funcionar: un soporte de pared, una barra de sonido y la garantía extendida. …",2.84,
2026-10-21T19:12:40.115000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Ana Torres Vega,ana.torres@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8d9,"Así quedó la exhibición de pantallas, ¿qué opinas?","Se ve ordenada y las pantallas de 55 y 65 pulgadas quedan a la altura de los ojos. …",4.37,https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg
2026-10-21T22:41:07.902000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Ana Torres Vega,ana.torres@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8d9,"Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.","¡Excelente cierre, Ana! …",3.12,
2026-10-20T17:22:45.051000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Diego Ramírez Peña,diego.ramirez@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8da,"Un cliente se lleva un celular de gama media, ¿qué le ofrezco?",Funda con mica incluida: …,1.97,
2026-10-20T17:30:18.664000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Diego Ramírez Peña,diego.ramirez@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8da,"Listo, vendí 2 fundas con mica.","¡Bien hecho, Diego! …",1.45,
```

Si te basta con la tabla plana de mensajes, el bucle es igual con `/data/messages/export`; los renglones ya vienen listos para escribirse:

```
def fetch_all_messages(token: str, filters: dict) -> list[dict]:
    """/data/messages pagina igual: pide hasta reunir 'total'."""
    rows, skip = [], 0
    while True:
        response = requests.get(
            f"{CODY_API_URL}/data/messages/export",
            params={**filters, "skip": skip, "limit": 500},
            headers={"Authorization": f"Bearer {token}"},
            timeout=120,
        )
        response.raise_for_status()
        page = response.json()
        rows.extend(page["conversations"])
        skip += 500
        if not page["conversations"] or skip >= page["total"]:
            return rows

# Los renglones ya vienen planos: se escriben directo al CSV
rows = fetch_all_messages(token, {
    "challenge_id": "6710f3a2c4b5d6e7f8091a2b",
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-10-31T23:59:59Z",
})
```

> **Para abrirlo en Excel sin problemas de acentos.** Escribe el CSV en UTF-8 con BOM (`utf-8-sig` en Python o `\uFEFF` al inicio en JavaScript), como en el ejemplo. Excel lo abre con acentos y eñes correctos con un doble clic.

> **¿Sin código?.** En Power Automate, Make, Zapier o n8n usa el módulo de solicitud HTTP con los mismos datos de los ejemplos cURL, un ciclo que aumente `skip` de 500 en 500 y el conector de Excel o Google Sheets para escribir los renglones. Guarda la credencial en el almacén de secretos de la herramienta.

## 13. Probar: Pruébalo antes en la documentación interactiva

Antes de automatizar, prueba tus filtros desde el navegador y mira la respuesta real.

### Paso 1. Autorízate con tu access token

Abre [api.public.cody-tech.com/api/docs](https://api.public.cody-tech.com/api/docs) y haz clic en **Authorize**. En **Value** pega el access token (sin la palabra «Bearer»), haz clic en **Authorize** y cierra con **Close**.

![Ventana Available authorizations de la documentación interactiva, con el campo Value para pegar el access token y los botones Authorize y Close.](https://docs.cody-tech.com/screenshots/public-api/swagger-authorize.png)

*El token de la captura es de ejemplo.*

### Paso 2. Abre la consulta y escribe tus filtros

En el grupo **data**, abre **GET /data/threads** y haz clic en **Try it out**. Escribe tu `challenge_id` y cualquier otro filtro que quieras probar; deja vacíos los demás.

![Operación GET /data/threads en modo Try it out: lista de parámetros con challenge_id ya escrito y los campos tenant_id, agent_id, date_from, date_to, created_from, created_to, user_ids y thread_id.](https://docs.cody-tech.com/screenshots/public-api/swagger-data-threads.png)

1. **challenge_id**: el `id` de la misión que obtuviste de `/gamification-challenge/list`.
2. **date_from** / **date_to**: días completos en formato `AAAA-MM-DD`.
3. **user_ids**: IDs separados por comas, máximo 100.

### Paso 3. Ejecuta y revisa la respuesta

Ajusta `limit` (para probar, 10 basta) y haz clic en **Execute**. Abajo verás la respuesta con el mismo formato que los ejemplos de esta guía, y el comando cURL equivalente para llevarlo a tu script.

![Final de los parámetros de GET /data/threads: search, include_messages, include_test_mode, skip y limit con 100, el botón Execute y la sección Responses.](https://docs.cody-tech.com/screenshots/public-api/swagger-data-threads-execute.png)

## 14. Si algo falla: Errores comunes y cómo resolverlos

La respuesta siempre explica el problema en el campo `detail`.

| Código | Cuándo pasa | Qué hacer |
| --- | --- | --- |
| `400` | Fechas invertidas (`date_from` después de `date_to`, `start` después de `end`), fecha con formato inválido, más de 100 `user_ids` o un ID mal escrito. | Lee `detail`: dice exactamente qué filtro corregir. |
| `401` | Token ausente, inválido o vencido (`Token expired`). | Renueva el access token y reintenta una vez. |
| `403` | La credencial no tiene permiso para consultar datos. | Pide al administrador que revise el rol de la persona en cuyo nombre actúa. |
| `422` | Un filtro con tipo incorrecto, por ejemplo `limit=1000` o `date_from=21/10/2026`. | Respeta los formatos de la tabla de filtros. |
| `200` con lista vacía | Ningún elemento cumple el filtro. | Revisa el `challenge_id`, amplía las fechas o recuerda el periodo por omisión de 30 días. |

##### 400 · fechas invertidas

```json
{
  "detail": "date_from must be before date_to"
}
```

##### 400 · demasiadas personas

```json
{
  "detail": "user_ids accepts at most 100 ids"
}
```

##### 400 · ID mal formado

```json
{
  "detail": "Invalid agent_id: 'coach-comercial'"
}
```

##### 401 · token vencido

```json
{
  "detail": "Token expired"
}
```

## 15. Lista de verificación: Antes de automatizar la exportación

Revisa estos puntos con quien construyó el proceso.

- La credencial tiene su propio nombre, actúa como un administrador y vive en un gestor de secretos, no en el código.
- El proceso renueva el access token al empezar y, ante un `401`, renueva y reintenta una sola vez.
- Las consultas por periodo envían siempre sus fechas (`start` / `end` o `date_from` / `date_to`) y no dependen del periodo por omisión.
- `user_ids` viaja en un solo parámetro separado por comas, con 100 IDs como máximo.
- El bucle de paginación usa `limit=500` y se detiene al reunir `total` o con una página vacía.
- Las conversaciones se descartan por `thread_id` si se repiten entre ejecuciones.
- Las fechas se tratan como UTC al guardarlas o mostrarlas.
- Los archivos con correos se guardan con acceso restringido; los que se comparten usan `/data/messages/export`.

## 16. Preguntas frecuentes: Dudas comunes

Lo que más nos preguntan al exportar datos.

### ¿Puedo exportar las conversaciones de todas las misiones a la vez?

Sí. Llama a `/data/threads` sin `challenge_id` y con un periodo (`date_from` / `date_to`): recibes todas las conversaciones, tengan misión o no. Cada una trae su `challenge_id` (o `null`) para que la agrupes después.

### ¿Por qué `/data/messages` no trae la respuesta del agente?

Porque está pensada como tabla de actividad: un renglón por mensaje de las personas, con el tiempo de respuesta. Si necesitas el texto de las respuestas, usa `/data/threads`, donde cada mensaje trae su `answer`.

### Cambié el nombre de una misión. ¿Qué nombre aparece en la exportación?

El actual. `topic`, `Topic` y `challenge.name` siempre muestran el nombre vigente de la misión, aunque la conversación haya ocurrido antes del cambio.

### ¿Aparecen las conversaciones de prueba?

No. Las conversaciones marcadas como de prueba (`test_mode: true`) quedan fuera, a menos que envíes `include_test_mode=true`.

### ¿Cada cuánto puedo correr la exportación?

Las veces que necesites, pero una exportación incremental diaria (con `created_from`) suele bastar y es mucho más ligera que descargar todo el historial cada vez.

## ¿Necesitas ayuda?

Si una exportación responde algo distinto a lo que describe esta guía, escríbenos con la consulta que hiciste (sin el token), la hora aproximada y el `detail` de la respuesta.
