Listar Registros

Consultar y filtrar registros (tareas) en Blue con potentes opciones de búsqueda y paginación.

Listar Registros

La consulta de tareas permite recuperar registros de Blue con opciones completas de filtrado, ordenación y paginación. Puedes consultar registros a través de empresas, proyectos o filtrar por criterios específicos como asignados, etiquetas y fechas.

Ejemplo Básico

Lista todos los registros en una empresa con parámetros mínimos:

query ListRecords {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
      }
    ) {
      items {
        id
        title
        done
        duedAt
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

Ejemplo Avanzado

Consulta registros con filtrado, ordenación y selección de campos completos:

query ListRecordsAdvanced {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_456", "project_789"]
        assigneeIds: ["user_123"]
        tagIds: ["tag_priority", "tag_urgent"]
        showCompleted: false
        dueStart: "2025-01-01T00:00:00Z"
        dueEnd: "2025-12-31T23:59:59Z"
        search: "product launch"
        excludeArchivedProjects: true
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "cf_status_123"
            customFieldType: "SELECT_SINGLE"
            values: ["In Progress", "Review"]
            op: "IN"
          }
        ]
        op: "AND"
      }
      sort: [duedAt_ASC, position_ASC]
      limit: 50
      skip: 0
    ) {
      items {
        id
        uid
        position
        title
        text
        html
        startedAt
        duedAt
        timezone
        color
        cover
        done
        archived
        createdAt
        updatedAt
        commentCount
        checklistCount
        checklistCompletedCount
        isRepeating
        todoList {
          id
          title
        }
        users {
          id
          name
          email
        }
        tags {
          id
          title
          color
        }
        customFields {
          id
          title
          type
          value
        }
        createdBy {
          id
          name
        }
      }
      pageInfo {
        totalPages
        totalItems
        page
        perPage
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Parámetros de Entrada

TodosFilter

Parámetro	Tipo	Requerido	Descripción
`companyIds`	[String!]!	✅ Sí	IDs de empresas o slugs para consultar
`projectIds`	[String!]	No	Filtrar por IDs de proyectos específicos o slugs
`todoIds`	[String!]	No	Recuperar tareas específicas por sus IDs
`assigneeIds`	[String!]	No	Filtrar por IDs de usuarios asignados
`tagIds`	[String!]	No	Filtrar por IDs de etiquetas
`tagColors`	[String!]	No	Filtrar por colores de etiquetas (formato hex)
`tagTitles`	[String!]	No	Filtrar por títulos de etiquetas
`todoListIds`	[String!]	No	Filtrar por IDs de listas de tareas
`todoListTitles`	[String!]	No	Filtrar por títulos de listas de tareas
`done`	Boolean	No	Filtrar por estado de finalización (obsoleto, usar showCompleted)
`showCompleted`	Boolean	No	Mostrar/ocultar tareas completadas (por defecto: verdadero)
`startedAt`	DateTime	No	Filtrar por fecha de inicio
`duedAt`	DateTime	No	Filtrar por fecha de vencimiento exacta
`dueStart`	DateTime	No	Inicio del rango de fecha de vencimiento (inclusive)
`dueEnd`	DateTime	No	Fin del rango de fecha de vencimiento (inclusive)
`search`	String	No	Buscar en título y contenido de texto
`q`	String	No	Parámetro de búsqueda alternativo (igual que búsqueda)
`excludeArchivedProjects`	Boolean	No	Excluir tareas de proyectos archivados
`coordinates`	JSON	No	Filtro geo-espacial para vista de mapa (coordenadas del polígono)
`fields`	JSON	No	Filtros de campos personalizados (ver filtrado avanzado)
`op`	FilterLogicalOperator	No	Operador lógico para filtros de campo (Y/O)

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
`filter`	TodosFilter!	✅ Sí	Criterios de filtrado para la consulta
`sort`	[TodosSort!]	No	Orden de clasificación (por defecto: array vacío)
`limit`	Int	No	Número de elementos por página (por defecto: 20, máximo: 500)
`skip`	Int	No	Número de elementos a omitir para la paginación (por defecto: 0)

Valores de TodosSort

Valor	Descripción
`assignees_ASC`	Ordenar por nombres de asignados ascendente
`assignees_DESC`	Ordenar por nombres de asignados descendente
`createdAt_ASC`	Ordenar por fecha de creación ascendente (más antiguo primero)
`createdAt_DESC`	Ordenar por fecha de creación descendente (más reciente primero)
`createdBy_ASC`	Ordenar por nombre de creador ascendente
`createdBy_DESC`	Ordenar por nombre de creador descendente
`duedAt_ASC`	Ordenar por fecha de vencimiento ascendente (más temprana primero)
`duedAt_DESC`	Ordenar por fecha de vencimiento descendente (más tardía primero)
`position_ASC`	Ordenar por posición ascendente (orden de lista por defecto)
`position_DESC`	Ordenar por posición descendente
`startedAt_ASC`	Ordenar por fecha de inicio ascendente
`startedAt_DESC`	Ordenar por fecha de inicio descendente
`title_ASC`	Ordenar por título alfabéticamente ascendente
`title_DESC`	Ordenar por título alfabéticamente descendente
`todoListPosition_ASC`	Ordenar por posición de lista de tareas ascendente
`todoListPosition_DESC`	Ordenar por posición de lista de tareas descendente
`todoListTitle_ASC`	Ordenar por título de lista de tareas ascendente
`todoListTitle_DESC`	Ordenar por título de lista de tareas descendente
`todoTags_ASC`	Ordenar por etiquetas ascendente
`todoTags_DESC`	Ordenar por etiquetas descendente

Valores de FilterLogicalOperator

Valor	Descripción
`AND`	Todas las condiciones deben coincidir
`OR`	Cualquier condición debe coincidir

Filtrado de Campos Personalizados

El fields parámetro admite filtrado avanzado por campos personalizados:

{
  "fields": [
    {
      "type": "CUSTOM_FIELD",
      "customFieldId": "cf_123",
      "customFieldType": "SELECT_SINGLE",
      "values": ["Option1", "Option2"],
      "op": "IN"
    }
  ]
}

Estructura del Filtro de Campos Personalizados

Campo	Tipo	Descripción
`type`	String	Debe ser "CUSTOM_FIELD"
`customFieldId`	String	ID del campo personalizado
`customFieldType`	String	Tipo del campo personalizado
`values`	[String!]	Valores para filtrar
`op`	String	Operador de comparación (IN, NOT_IN, EQ, etc.)

Tipos de Campos Personalizados Soportados

Campos de texto: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
Campos numéricos: CURRENCY, NUMBER, FORMULA
Campos de selección: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
Campos de referencia: REFERENCE, LOOKUP
Campos de fecha: DATE

Campos de Respuesta

TodosResult

Campo	Tipo	Descripción
`items`	[Todo!]!	Array de registros de tareas
`pageInfo`	PageInfo!	Metadatos de paginación

PageInfo

Campo	Tipo	Descripción
`totalPages`	Int	Número total de páginas disponibles
`totalItems`	Int	Número total de elementos en todas las páginas
`page`	Int	Número de página actual (calculado a partir de omitir/límite)
`perPage`	Int	Número de elementos por página
`hasNextPage`	Boolean!	Si hay una página siguiente
`hasPreviousPage`	Boolean!	Si hay una página anterior

Campos de Tareas

Campo	Tipo	Descripción
`id`	ID!	Identificador único
`uid`	String!	Identificador único amigable
`position`	Float!	Posición en la lista
`title`	String!	Título de la tarea
`text`	String!	Contenido de texto plano
`html`	String!	Contenido formateado en HTML
`startedAt`	DateTime	Fecha/hora de inicio
`duedAt`	DateTime	Fecha/hora de vencimiento
`timezone`	String	Zona horaria para fechas
`color`	String	Indicador visual de color
`cover`	String	URL de imagen de portada
`done`	Boolean!	Estado de finalización
`archived`	Boolean!	Estado de archivo
`createdAt`	DateTime!	Marca de tiempo de creación
`updatedAt`	DateTime!	Marca de tiempo de última actualización
`commentCount`	Int!	Número de comentarios
`checklistCount`	Int!	Total de elementos de la lista de verificación
`checklistCompletedCount`	Int!	Elementos de la lista de verificación completados
`isRepeating`	Boolean!	Si la tarea es recurrente
`isRead`	Boolean	Estado de lectura para el usuario actual
`isSeen`	Boolean	Estado visto para el usuario actual
`todoList`	TodoList!	Lista de tareas padre
`users`	[User!]!	Usuarios asignados
`tags`	[Tag!]!	Etiquetas asociadas
`checklists`	[Checklist!]!	Listas de verificación asociadas
`createdBy`	User	Usuario que creó la tarea
`customFields`	[CustomField!]!	Valores de campos personalizados
`dependOn`	[Todo!]	Tareas bloqueantes (dependencias)
`dependBy`	[Todo!]	Tareas dependientes (bloqueadas por esta)
`timeTracking`	TimeTracking	Datos de seguimiento del tiempo

Permisos Requeridos

Los usuarios deben tener acceso apropiado para consultar registros:

Tipo de Acceso	Requisitos
Company Access	User must be a member of the company
Project Access	User must have access to specific projects (if filtering by project)
Todo Visibility	Depends on user's role and permissions:
- `VIEW_ONLY`	Can view all accessible todos
- `COMMENT_ONLY`	Can view all accessible todos
- `CLIENT`	May be restricted to assigned todos only
- `MEMBER`	Can view all project todos
- `ADMIN`	Can view all project todos
- `OWNER`	Can view all company todos

Restricciones Especiales:

Los usuarios con permiso showOnlyAssignedTodos solo pueden ver tareas asignadas a ellos
Las listas de tareas ocultas (basadas en la configuración de roles) se excluyen automáticamente
Los permisos basados en etiquetas pueden filtrar aún más los resultados

Respuestas de Error

Errores Comunes

La consulta maneja errores de manera elegante y devuelve resultados vacíos para:

IDs de empresa no válidos
Proyectos inaccesibles
Escenarios de permiso denegado

Para errores graves, pueden devolverse errores de GraphQL:

{
  "errors": [{
    "message": "Query timeout exceeded",
    "extensions": {
      "code": "QUERY_TIMEOUT"
    }
  }]
}

Notas Importantes

Rendimiento

Límite por defecto: 20 elementos por página (aplicado automáticamente si no se especifica)
Límite máximo: 500 elementos por solicitud (capped automáticamente)
Optimización: Las consultas utilizan uniones optimizadas con STRAIGHT_JOIN para el mejor rendimiento
Indexación: Los campos de filtrado comunes están indexados para consultas rápidas
Campos personalizados: Amplio soporte para filtrado de campos personalizados con un impacto mínimo en el rendimiento
Consultas geográficas: Soporta filtrado de coordenadas basado en polígonos para vistas de mapas

Filtrado de Fechas

Los rangos de fechas son inclusivos
Soporta rangos de fechas superpuestos (tareas que comienzan o terminan dentro del rango)
Las fechas nulas se manejan de manera elegante (las tareas sin fechas de vencimiento no coincidirán con los filtros de fecha)
Todas las fechas deben estar en formato ISO 8601

Comportamiento de Búsqueda

La búsqueda no distingue entre mayúsculas y minúsculas
Busca tanto en el título como en el contenido de texto
Se admite la coincidencia de palabras parciales
Se manejan adecuadamente los caracteres especiales

Estrategia de Paginación

Usa skip y limit para paginación basada en desplazamiento
Calcula la página actual: page = Math.floor(skip / limit) + 1
Para conjuntos de datos grandes, considera usar filtros para reducir el tamaño de los resultados
Siempre verifica hasNextPage antes de incrementar el desplazamiento

Endpoints Relacionados

Crear Registro: Usa la mutación createTodo para crear nuevos registros
Actualizar Registro: Usa la mutación updateTodo para modificar registros
Eliminar Registro: Usa la mutación deleteTodo para eliminar registros
Listar Campos Personalizados: Consulta los campos personalizados disponibles para filtrado
Listar Proyectos: Consulta los proyectos disponibles para filtrado