> ## Documentation Index > Fetch the complete documentation index at: https://docs.roofkit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Listar registros del objeto > Lista registros de un objeto. La paginación usa limit, next_cursor y has_more. Vuelve a solicitar con next_cursor hasta que has_more sea false. Una lectura de un objeto personalizado sin search, en orden de created_at o updated_at, sigue un cursor keyset y devuelve cada registro exactamente una vez. El orden predeterminado es created_at, del más reciente al más antiguo. Una página de esa lectura lee como máximo 1,000 registros, así que una página con filtros puede contener menos registros que limit, o ninguno, mientras has_more sea true. No uses el tamaño de la página para decidir que la lista terminó. Una lectura con search, con un orden por otro campo, o sobre un objeto nativo como Contacts pagina por número, e is_capped es true cuando la ventana del motor se detiene en 1,000 filas. Contacts solo lista leads finalizados. Un cursor solo funciona con el orden que lo emitió. Un cursor malformado o que no coincide devuelve 400. **Scopes requeridos:** `data_objects.read` ## OpenAPI ````yaml /es/api-reference/openapi.yaml get /api/v1/objects/{object_id}/records openapi: 3.1.0 info: title: RoofKit Partner API version: 1.0.0 summary: API REST JSON para integraciones externas de socios de RoofKit. contact: name: RoofKit Engineering description: >- RoofKit Partner API v1 autentica solicitudes con API keys del workspace. Las API keys vinculan cada solicitud exactamente a un workspace; las rutas de Partner API no aceptan roofer_id, workspace_id ni identificadores de tenant. Los endpoints autenticados están limitados a 60 solicitudes por minuto por API key, método y plantilla de ruta; los intentos de autenticación inválidos se limitan por separado a 20 solicitudes por minuto por cliente y endpoint. Los parámetros y campos de fecha/hora aceptan ISO 8601 con Z o un desfase ±HH:MM, por ejemplo 2026-09-07T04:00:00Z o 2026-09-07T00:00:00-04:00. Ambos indican el mismo instante y devuelven el mismo resultado. Codifica + como %2B en una query string. Las respuestas usan UTC. Una fecha/hora sin desfase, por ejemplo 2026-09-07T04:00:00, está obsoleta. Hasta la fecha de retiro, 2027-01-10T00:00:00Z, se interpreta como UTC, y la respuesta incluye un header `Deprecation` (RFC 9745) y un header `Sunset` (RFC 8594). A partir de la fecha de retiro, se requiere Z o un desfase ±HH:MM. Desde entonces, una fecha/hora sin desfase devuelve 400 con el código `VALIDATION_ERROR`, y la respuesta no incluye ningún header `Deprecation` ni `Sunset`. Cada API key tiene solo los scopes que un propietario o administrador del workspace eligió al crear la key, y sus scopes nunca cambian. Cada operación indica los scopes que requiere en `x-required-scopes`. Una key nueva en Configuración empieza con el nivel predefinido Solo lectura: `leads.read`, `analytics.read`, `reports.read` y `data_objects.read`. Una key de Solo lectura puede llamar a todas las operaciones de lectura excepto las exportaciones, las lecturas de Sales Visualizer y los Data Objects en papelera, y no puede llamar a ninguna operación de escritura. Una llamada que necesita un scope que la key no tiene devuelve 403 `FORBIDDEN`, y `error.details.required_scope` indica un scope faltante. servers: - url: https://api.roofkit.ai description: Origen canónico de RoofKit Partner API security: - ApiKeyBearer: [] tags: - name: Foundation description: Endpoints base de autenticación y contrato. - name: Leads description: Endpoints de sincronización de leads para CRM de socios. - name: Attribution description: >- Endpoints de atribución de marketing, analíticas de campañas e ingesta de eventos para socios. - name: Pipeline description: Metadatos del pipeline de leads legibles para socios. - name: Reports description: >- Endpoints para importar, listar, obtener, exportar y descargar reportes de socios. - name: Visualizer description: >- Endpoints de Partner para crear Sales Visualizer, generar visualizaciones, crear enlaces alojados de subida de fotos, leer imágenes, consultar el historial de sesión y crear enlaces compartidos. - name: Estimates description: >- Creación y lectura de Budget Estimates de Partner para el workspace vinculado a la key. - name: Objects description: >- Endpoints de Partner para descubrimiento, esquema, registros, relaciones, vistas y administración de Data Objects. paths: /api/v1/objects/{object_id}/records: get: tags: - Objects summary: Listar registros del objeto description: >- Lista registros de un objeto. La paginación usa limit, next_cursor y has_more. Vuelve a solicitar con next_cursor hasta que has_more sea false. Una lectura de un objeto personalizado sin search, en orden de created_at o updated_at, sigue un cursor keyset y devuelve cada registro exactamente una vez. El orden predeterminado es created_at, del más reciente al más antiguo. Una página de esa lectura lee como máximo 1,000 registros, así que una página con filtros puede contener menos registros que limit, o ninguno, mientras has_more sea true. No uses el tamaño de la página para decidir que la lista terminó. Una lectura con search, con un orden por otro campo, o sobre un objeto nativo como Contacts pagina por número, e is_capped es true cuando la ventana del motor se detiene en 1,000 filas. Contacts solo lista leads finalizados. Un cursor solo funciona con el orden que lo emitió. Un cursor malformado o que no coincide devuelve 400. operationId: List object records parameters: - $ref: '#/components/parameters/ObjectId' - $ref: '#/components/parameters/Search' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/ObjectViewId' - $ref: '#/components/parameters/ObjectFiltersJson' - $ref: '#/components/parameters/ObjectSortsJson' responses: '200': description: Página de registros. content: application/json: schema: $ref: '#/components/schemas/ObjectRecordListResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: ObjectId: name: object_id in: path required: true description: >- Id del objeto, clave de sistema como system:leads, o slug del descubrimiento. x-docs-test-value: system:leads schema: type: string minLength: 1 maxLength: 200 Search: name: search in: query schema: type: string maxLength: 200 Cursor: name: cursor in: query description: >- Cursor opaco devuelto por respuestas de listado/exportación. Envíalo de vuelta sin cambios; los cursores malformados devuelven 400. schema: type: string maxLength: 500 Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 ObjectViewId: name: view_id in: query schema: type: string maxLength: 200 ObjectFiltersJson: name: filters_json in: query description: >- Texto JSON de un ObjectFilterQuery. Envía un array de filtros que deben coincidir todos, o un objeto con filters y un filtro avanzado cuyas reglas se unen con and u or. Cada filtro indica un campo en fieldId por su id o su clave, tal como los lista GET /api/v1/objects/{object_id}. Operadores: is_empty e is_not_empty no reciben value. equals, not_equals, contains y has_reached reciben value. any_of recibe un array de cadenas. greater_than y less_than reciben un número, y between recibe value y valueTo. before y after reciben una fecha (YYYY-MM-DD) o una fecha/hora ISO 8601 y excluyen el día que indican. within_range recibe value y valueTo e incluye ambos días. Una fecha sola cubre todo el día UTC. Una fecha/hora con desfase se convierte a UTC. Sin filters_json, la lectura aplica los filtros de view_id, o ninguno. Un JSON inválido, un operador desconocido, un value faltante, un campo desconocido o un campo que no se puede filtrar devuelve 400 con la ruta de cada problema. Ejemplo, registros creados en octubre de 2026: [{"fieldId":"created_at","operator":"within_range","value":"2026-10-01","valueTo":"2026-10-31"}] schema: type: string maxLength: 20000 contentMediaType: application/json contentSchema: $ref: '#/components/schemas/ObjectFilterQuery' ObjectSortsJson: name: sorts_json in: query description: >- Texto JSON de un array de ObjectSort. Cada orden indica un campo en fieldId por su id o su clave. Sin sorts_json, la lectura usa el orden de view_id, o created_at, del más reciente al más antiguo. Solo un único orden por created_at o updated_at conserva el cursor keyset. Cualquier otro orden pagina por número. Un JSON inválido, un campo desconocido o un campo de fórmula devuelve 400. Ejemplo, registros más antiguos primero: [{"fieldId":"created_at","direction":"asc"}] schema: type: string maxLength: 20000 contentMediaType: application/json contentSchema: type: array maxItems: 5 items: $ref: '#/components/schemas/ObjectSort' schemas: ObjectRecordListResponse: type: object additionalProperties: false required: - records - pagination properties: records: type: array items: $ref: '#/components/schemas/ObjectRecord' pagination: $ref: '#/components/schemas/ObjectCursorPagination' ObjectRecord: type: object additionalProperties: false required: - id - object_id - display_label - values - relationships - created_at - updated_at properties: id: type: string object_id: type: string record_key: type: - string - 'null' display_label: type: string values: $ref: '#/components/schemas/JsonRecord' relationships: type: array items: $ref: '#/components/schemas/ObjectRecordRelationship' stage_history: description: >- La primera fecha en que el registro entró en cada opción de cada campo de estado, de la más antigua a la más reciente. Aparece en las lecturas de registros. Un registro de Contacts o Reports no la tiene. type: array items: $ref: '#/components/schemas/ObjectRecordStageEntry' stage_dates: description: >- Las fechas de cita, venta ganada y pérdida del registro. Aparece en las lecturas de registros. Es null cuando el objeto no tiene campo de estado. oneOf: - $ref: '#/components/schemas/ObjectRecordStageDates' - type: 'null' created_at: type: string format: date-time updated_at: type: string format: date-time ObjectCursorPagination: type: object additionalProperties: false required: - limit - next_cursor - has_more properties: limit: type: integer minimum: 1 maximum: 10000 next_cursor: type: - string - 'null' has_more: type: boolean is_capped: type: boolean total: type: integer minimum: 0 description: >- Cantidad exacta de filas que coinciden con la solicitud. Algunas lecturas la incluyen y otras no, así que trátala como opcional. ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message - request_id properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string request_id: type: string details: type: object additionalProperties: true JsonRecord: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: oneOf: - type: string - type: number - type: boolean - type: 'null' ObjectRecordRelationship: description: Un vínculo de este registro con un registro de otro objeto. type: object additionalProperties: true properties: id: type: string relationship_definition_id: type: string field_id: type: string source_object_id: type: string source_record_id: type: string target_object_id: type: string target_object_slug: type: string target_record_id: type: string description: >- Para un vínculo con un Contact, el id que recibe GET /api/v1/leads/{lead_id}. target_label: type: string target_attribution: description: >- La atribución de marketing de un Contact vinculado, el mismo objeto que Lead.attribution. Aparece en las lecturas de registros solo para vínculos con Contacts. Es null cuando el Contact fue eliminado o borrado. oneOf: - $ref: '#/components/schemas/Attribution' - type: 'null' ObjectRecordStageEntry: description: La primera entrada del registro en una opción de estado. type: object additionalProperties: false required: - field_id - field_key - option_id - option_label - entered_at properties: field_id: type: string field_key: type: string option_id: type: string option_label: type: string entered_at: type: string format: date-time ObjectRecordStageDates: description: >- Fechas clave del campo Stage. Cada fecha usa la misma coincidencia de etapa que las métricas Appointments y Won del dashboard, así que un rango de fechas cuenta los mismos registros. type: object additionalProperties: false required: - appointment_at - won_at - lost_at properties: appointment_at: description: >- La primera entrada en una etapa de cita, como Appointment o Qualified. Una etapa de visita como Appointment made no cuenta. type: - string - 'null' format: date-time won_at: description: La primera entrada en una etapa ganada, como Won o Sold. type: - string - 'null' format: date-time lost_at: description: La primera entrada en una etapa perdida, como Lost o Dead. type: - string - 'null' format: date-time ErrorCode: type: string enum: - UNAUTHORIZED - FORBIDDEN - RATE_LIMITED - VALIDATION_ERROR - NOT_FOUND - CONFLICT - INSUFFICIENT_CREDITS - INTERNAL_ERROR Attribution: type: object additionalProperties: false properties: source: type: - string - 'null' medium: type: - string - 'null' campaign: type: - string - 'null' content: type: - string - 'null' conversion_url: type: - string - 'null' format: uri entry: description: >- Entrada al sitio web de este punto de contacto. Se omite cuando no está definida. No reemplaza source. type: string enum: - button - embed - direct responses: ValidationError: description: El payload, query o header requerido de la solicitud no es válido. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: API key ausente, malformada, revocada, eliminada o desconocida. headers: WWW-Authenticate: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- La API key no tiene un scope requerido, o el workspace no está activo. Un fallo de scope indica un scope faltante en `details.required_scope`. Cuando la búsqueda de la key rechaza la llamada, `details.missing_scopes` lista cada scope requerido que la key no tiene. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_scope: summary: Una key de Solo lectura llama a una operación de escritura value: error: code: FORBIDDEN message: 'API key does not include the required scope: leads.write.' request_id: req_123 details: required_scope: leads.write missing_scopes: - leads.write NotFound: description: Recurso no encontrado en el workspace vinculado a la key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: >- Rate limit excedido para esta key y endpoint o para el bucket de autenticación inválida. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Error interno de autenticación o del servidor. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: RateLimitLimit: description: Cantidad máxima de solicitudes permitidas en la ventana actual. schema: type: string RateLimitRemaining: description: Solicitudes restantes en la ventana actual. schema: type: string RateLimitReset: description: Timestamp ISO cuando se reinicia la ventana actual de rate limit. schema: type: string format: date-time RetryAfter: description: Segundos hasta que el llamador debería reintentar. schema: type: string securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: RoofKit API key description: 'Usa `Authorization: Bearer rk_live_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.