> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar grupos de registro (o buscar uno por nombre)
> Sin `name`: devuelve los grupos de registro de la cuenta, más nuevo primero, paginado por conjunto de teclas. Con `name`: devuelve como máximo un grupo de registros que coincida con ese nombre exacto (lista vacía si no hay coincidencia). Requiere `telemetry:DescribeLogGroups`.
Requiere la acción de IAM **`telemetry:DescribeLogGroups`**. Consulte [permisos de telemetría](/telemetry/permissions) para obtener la lista completa, lo que cubre cada una y un ejemplo de directiva.
## OpenAPI
````yaml /es/api-reference/specs/telemetry.yaml get /v1/log-groups
openapi: 3.0.3
info:
title: API de telemetría basaltica
version: 1.0.0
description: >
API de telemetría regional: grupos de registros + ingesta/búsqueda de
registros, métricas de ClickHouse (escritura_remota + consulta estructurada
con sobres JSON compatibles con Prometheus), ingesta de intervalos y
búsqueda/detalle de trazas + configuración de trazas por cuenta.
Las referencias de solicitud de grupo de registro aceptan UUID, CRN o
nombres exactos de ámbito de cuenta, clasificados por sintaxis sin fallback
de búsqueda. Los CRN deben coincidir con el identificador de cuenta
autenticado y la región de entrega. Los registros HTTP y gRPC OTLP usan
basaltic.log_group, que se refiere a service.name, con el mismo contrato de
referencia. Los identificadores de traza/intervalo, las etiquetas de métrica
y las dimensiones de búsqueda de región son valores de protocolo,
independientes de la resolución del recurso.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://telemetry.{region}.basaltic.sh
description: Endpoint de API regional (uno por región)
variables:
region:
default: sa-saopaulo-1
description: Código de región
security:
- BearerAuth: []
paths:
/v1/log-groups:
get:
tags:
- Telemetry
summary: Listar grupos de registro (o buscar uno por nombre)
description: >
Sin `name`: devuelve los grupos de registro de la cuenta, más nuevo
primero, paginado por conjunto de teclas. Con `name`: devuelve como
máximo un grupo de registros que coincida con ese nombre exacto (lista
vacía si no hay coincidencia). Requiere `telemetry:DescribeLogGroups`.
operationId: listLogGroups
parameters:
- name: name
in: query
description: Filtro de nombre exacto, intersecado con crn y paginación.
schema:
type: string
example: app/prod/api
- name: crn
in: query
description: >-
Filtro CRN de telemetría/log-group exacto en la cuenta autenticada y
la región de servicio. CRNs malformados o vacíos devuelven 400. Los
CRN extranjeros válidos o no coincidentes devuelven una página
vacía. Intersecado con nombre y paginación.
schema:
type: string
example: crn:telemetry:sa-saopaulo-1:my-account:log-group/app/prod/api
- $ref: '#/components/parameters/LimitDefault50'
- $ref: '#/components/parameters/Marker'
responses:
'200':
description: Página de grupos de registro
content:
application/json:
schema:
$ref: '#/components/schemas/LogGroupListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
components:
parameters:
LimitDefault50:
name: limit
in: query
description: >-
Número máximo de artículos a devolver. Un valor por encima del máximo se
le aplica en lugar de rechazarlo, por lo que una página más corta que la
que solicitaste es normal — page until `meta.has_more` es falso, no
hasta que una página se vea corta.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
example: 50
Marker:
name: marker
in: query
description: >-
Cursor de paginación opaco. Hacer eco del valor `meta.marker` de la
página anterior para buscar la siguiente; no construirlo ni analizarlo.
La forma interna del token varía según el punto final (un ID de recurso,
una marca de tiempo, etc.) y no se garantiza su estabilidad entre
versiones.
required: false
schema:
type: string
example: 550e8400-e29b-41d4-a716-446655440000
schemas:
LogGroupListResponse:
type: object
properties:
log_groups:
type: array
items:
$ref: '#/components/schemas/LogGroup'
meta:
$ref: '#/components/schemas/PaginationMeta'
LogGroup:
type: object
properties:
id:
type: string
format: uuid
example: 4a7b2c8d-9e1f-4a2b-8c3d-5e6f7a8b9c0d
crn:
type: string
description: CRN del grupo de registro (utilizado como el recurso IAM ARN)
example: crn:telemetry:sa-saopaulo-1:my-account:log-group/app-prod-api
account_id:
type: string
format: uuid
description: 'Cuenta de propietario: la valla de inquilino para este grupo'
example: 9b2e4d11-6c3a-4f8e-bd47-1a2b3c4d5e6f
name:
type: string
description: >-
1..512 caracteres, [A-Za-z0-9_./#-]. No se permite el carácter "/"
inicial. Los nombres de los recursos no deben comenzar con el
prefijo literal crn: ni ser UUID (en cualquier caso, en las formas
canónica, compacta, entre corchetes o urn:uuid:).
example: app/prod/api
description:
type: string
example: Production API request logs
retention_days:
type: integer
nullable: true
minimum: 1
maximum: 3650
description: 1..3650 días, o null para nunca expirar
example: 30
kms_key_unavailable:
type: boolean
readOnly: true
description: >-
True cuando la clave enlazada ha sido eliminada. El CRN se omite,
pero el enlace permanece cifrado bajo su identidad de clave
original; esto no selecciona el cifrado de plataforma o texto sin
formato.
kms_key_crn:
type: string
description: >-
CRN de clave KMS. Se omite para texto plano o cuando
kms_key_unavailable es verdadero.
example: crn:kms:sa-saopaulo-1:my-account:key/service-key
tags:
type: object
additionalProperties:
type: string
created_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
updated_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
PaginationMeta:
type: object
properties:
total:
type: integer
description: Número total de artículos
example: 150
limit:
type: integer
description: Número de artículos por página
example: 20
marker:
type: string
description: >-
Cursor opaco para la página siguiente. Pasalo de vuelta como el
parámetro de consulta `marker`; trátalo como un token, no como un
valor para analizar.
example: 550e8400-e29b-41d4-a716-446655440000
has_more:
type: boolean
description: Si hay más artículos
example: true
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de error que identifica el tipo de error
example: INVALID_INPUT
message:
type: string
description: Mensaje de error legible por el ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores no sensibles opcionales para la interpolación de errores
localizados, codificados por código de error. Nunca presente por
errores del servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuración
example: 550e8400-e29b-41d4-a716-446655440000
responses:
BadRequest:
description: Parámetros de solicitud no válidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INVALID_INPUT
message: Invalid request parameters
request_id: 550e8400-e29b-41d4-a716-446655440000
Unauthorized:
description: Se requiere autenticación o el token no es válido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Permisos insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
InternalServerError:
description: Error interno del servidor
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INTERNAL_ERROR
message: An internal error occurred
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >+
Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer
`. Esta es la forma recomendada de autenticación.
Obtén el token intercambiando el par de claves de acceso de una cuenta
de servicio en `POST /v1/oauth/token` con
`grant_type=client_credentials`. Es el flujo estándar de credenciales de
cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar
el token por ti.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Los tokens duran una hora por defecto. El mismo par de claves de acceso
también sirve como credencial AWS SigV4 para el endpoint de objetos
compatible con S3, que solo acepta ese método de autenticación.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.