---
title: "Obtener valores posibles para un criterio"
method: POST
path: "/dimensions/values"
tags: ["Segmentation"]
---

# Obtener valores posibles para un criterio

`POST /dimensions/values`

## Request

- Base URL: `http://localhost:8081`
- URL: `http://localhost:8081/dimensions/values`
- Auth: HTTP bearer

Retorna los valores disponibles para un criterio específico, filtrados por tenant.

**Criterios económicos** (`economic_metric`: total_spent, average_spent, cashless_*): no tienen
valores enumerables; responde 400 con `CRITERION_HAS_NO_VALUES` (#57).

**Para criterios TEXT**: Retorna array de strings únicos
```json
["España", "Francia", "Portugal"]
```

**Para criterios ENTITY**: Retorna array de objetos con id, name y description (opcional)
```json
[
  {"id": "evt_123", "name": "Primavera Sound 2024", "description": "15 Jul 2024"},
  {"id": "evt_456", "name": "Mad Cool Festival 2024", "description": "20 Aug 2024"}
]
```

El campo `description` es opcional y solo aparece en ciertos criterios:
- `attended_event`: Fecha del evento
- `ticket_type`: Nombre del evento al que pertenece

**Para custom fields**: Incluir `context.property_name` en el body
```json
{
  "criterion_id": "user_custom_field",
  "context": {
    "property_name": "preferred_music_genre"
  }
}
```

Soporta búsqueda avanzada con `search_term` (v3.20.0): multi-término, normalización de acentos,
búsqueda en description y ranking por relevancia. Completamente retrocompatible.

## Request body

- DimensionValuesRequest
  - `criterion_id` string, required: ID del criterio
  - `search_term` string: Filtro de búsqueda opcional con soporte completo para: - **Multi-término**: los espacios actúan como AND. `"vip barakaldo"` busca entidades que contengan AMBOS términos (en cualquier orden y campo). - **Normalización de acentos**: `"euforia"` encuentra `"Eufòria"`, `"malaga"` encuentra `"Málaga"`. Funciona en ambas direcciones. - **Búsqueda en description**: para criterios ENTITY con campo description configurado (ej: `attended_event`, `ticket_type`), la búsqueda se extiende también a la descripción. - **Ranking por relevancia**: exact match primero, luego starts-with, luego contains. - **Case-insensitive**: `VIP` = `vip` = `Vip`. - **Retrocompatible**: si se omite, el comportamiento es idéntico a versiones anteriores.
  - `limit` integer: Límite de resultados por página
  - `offset` integer: **NEV-1714** — Desplazamiento cero-basado para paginación por offset. - Cuando está ausente o es 0: devuelve la primera página (comportamiento idéntico a v3.20). - Cuando se proporciona: omite los primeros `offset` resultados antes de aplicar `limit`. - **Restricciones**: debe ser un entero >= 0. Valores mayores a 10 000 son rechazados con HTTP 400. **Uso para cargar más resultados (infinite scroll):** ``` // Página 1 { "criterion_id": "attended_event", "limit": 20, "offset": 0 } // Página 2 { "criterion_id": "attended_event", "limit": 20, "offset": 20 } // Página 3 { "criterion_id": "attended_event", "limit": 20, "offset": 40 } ```
  - `context` object: Contexto adicional (para custom fields)
    - `property_name` string: Nombre del custom field (solo caracteres alfanuméricos, guión, punto y espacio)

## Response `200`

Valores obtenidos exitosamente

- DimensionValuesResponse
  - `success` boolean, required
  - `values` union, required
    - string[]: Array de valores TEXT
    - EntityValue[]: Array de valores ENTITY
      - `id` string, required: ID de la entidad
      - `name` string, required: Nombre de la entidad
      - `description` string: Información adicional contextual (opcional). Para eventos muestra la fecha, para tipos de entrada muestra el evento.
  - `has_more` boolean, required: **NEV-1714** — Indica si existen resultados adicionales más allá de la página actual. - `false`: los `values` devueltos son todos los resultados disponibles. - `true`: existen más resultados; envía la siguiente petición con `offset += limit`. Siempre presente en la respuesta (incluso cuando no se envió `offset`). Calculado con el truco LIMIT+1 para evitar un costoso COUNT(*). Los consumidores existentes que solo leen `values` no se ven afectados (cambio aditivo).

## Other responses

- `400`: Solicitud inválida
- `403`: Acceso denegado antes de ejecutar ninguna consulta. Dos casos: - **Rol no admitido** (`error.code: FORBIDDEN`): las rutas de datos solo admiten tokens con rol ADMIN, OWNER o SUPERADMIN (los `campaign_service_token` de nev-api llevan rol ADMIN). Un token de fan (USER), STAFF, EXTERNAL o sin rol recibe 403. - **Selección ajena** (`code: ACTIVE_TENANT_FORBIDDEN`): la organización seleccionada (`activeTenantId`) no pertenece a la jerarquía actual de `tenantId`.
- `500`: Error interno del servidor
- `503`: No se pudo leer la jerarquía de tenants (MongoDB no disponible). Reintentable; nunca se sustituye por un ámbito parcial o global.

---

[API](https://skmtc.dev/nevent/apis/nevent-data-api.md) · [All operations](https://skmtc.dev/nevent/apis/nevent-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nevent/apis/nevent-data-api/revisions/81035d32c1c1?raw)