# QueryMetrics
<a name="CloudWatch-PromQL-API-QueryMetrics"></a>

La operación `QueryMetrics` evalúa una consulta instantánea de PromQL en un único momento o evalúa una consulta en un intervalo de tiempo.

Verbos HTTP válidos  
`GET`, `POST`

URI válidos  
`/api/v1/query`: evalúa una consulta instantánea en un único momento.  
`/api/v1/query_range`: evalúa una consulta en un intervalo de tiempo.

La URL de solicitud completa combina el host de supervisión de CloudWatch de la región de AWS con la ruta de operación, por ejemplo, `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/query`. Para obtener más información sobre los puntos de conexión, la firma y los permisos de IAM necesarios, consulte [Consultas PromQL](CloudWatch-PromQL-Querying.md).

## Parámetros de consulta de URL
<a name="CloudWatch-PromQL-API-QueryMetrics-Parameters"></a>

Los siguientes parámetros se pasan en la cadena de consulta de la URL para las solicitudes `GET` o como campos de cuerpo codificados como formulario para las solicitudes `POST`.


| Parámetro | Aplica a | Descripción | 
| --- | --- | --- | 
| `query` | Ambos | Obligatorio. La cadena de expresión de PromQL que se evaluará. La expresión debe seleccionar una métrica por nombre, por ejemplo, `{"http.server.active_requests"}` o `{__name__="http.server.active_requests"}`. No se admite la selección de series solo por etiquetas, sin un nombre de métrica. | 
| `time` | `/api/v1/query` | Opcional. Marca de tiempo de evaluación como marca de tiempo RFC 3339 o marca de tiempo de Unix. El valor predeterminado es la hora actual del servidor. | 
| `start` | `/api/v1/query_range` | Obligatorio. Inicio del intervalo de tiempo, como una marca de tiempo RFC 3339 o una marca de tiempo de Unix. | 
| `end` | `/api/v1/query_range` | Obligatorio. Final del intervalo de tiempo, como una marca de tiempo RFC 3339 o una marca de tiempo de Unix. | 
| `step` | `/api/v1/query_range` | Obligatorio. Ancho del paso de resolución de la consulta, en formato `duration` o como número de segundos de coma flotante. | 
| `limit` | Ambos | Opcional. Número máximo de series temporales únicas que se devolverán, de `1` a `500`. Si no especifica `limit`, CloudWatch devuelve el máximo (500). Consulte [Límite de resultados](#CloudWatch-PromQL-API-QueryMetrics-Limits). | 

**Duración**

En una API compatible con Prometheus, una `duration` es un número, seguido inmediatamente de una de las siguientes unidades:
+ `ms` milisegundos
+ `s` segundos
+ `m` minutos
+ `h` horas
+ `d` días, suponiendo que un día siempre tenga 24 horas
+ `w` semanas, suponiendo que una semana siempre tenga 7 días
+ `y` años, suponiendo que un año siempre tenga 365 días

## Permisos de IAM necesarios
<a name="CloudWatch-PromQL-API-QueryMetrics-IAM"></a>

Para llamar a `QueryMetrics`, la identidad que hace la llamada debe tener las siguientes acciones de IAM:
+ `cloudwatch:GetMetricData`
+ `cloudwatch:ListMetrics`

Para ver la asignación completa de acciones de IAM para todas las operaciones de PromQL, consulte [Permisos de IAM para PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).

## Límite de resultados
<a name="CloudWatch-PromQL-API-QueryMetrics-Limits"></a>

Una sola respuesta `/api/v1/query` o `/api/v1/query_range` puede devolver hasta **500 series temporales únicas**. Para solicitar menos resultados, pase el parámetro `limit` con un valor comprendido entre `1` y `500`. Si no especifica `limit`, CloudWatch devuelve el máximo.

Cuando las series temporales coincidentes superan el límite, la respuesta se trunca y se incluye un mensaje en el campo `warnings` de Prometheus estándar. El código de estado HTTP continúa siendo `200`.

Para ver la lista completa de los límites de PromQL, incluidos el TPS, la simultaneidad y los periodos de escaneo de 24 horas, consulte [Límites y restricciones de PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-Limits).

## Solicitud de ejemplo
<a name="CloudWatch-PromQL-API-QueryMetrics-Sample"></a>

La siguiente solicitud `POST` pasa la expresión PromQL en un cuerpo codificado como formulario. Los caracteres especiales como `{`, `}` y `"` están codificados como porcentaje.

```
POST /api/v1/query HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Content-Type: application/x-www-form-urlencoded
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36

query=sum(%7B%22http.server.active_requests%22%7D)
```

La misma llamada con `awscurl`:

```
awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/query' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'query=sum({"http.server.active_requests"})'
```

## Respuesta de ejemplo
<a name="CloudWatch-PromQL-API-QueryMetrics-Response"></a>

Una respuesta correcta utiliza el sobre JSON estándar de Prometheus:

```
HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [
            {
                "metric": {},
                "value": [
                    1780000000.000,
                    "42"
                ]
            }
        ]
    }
}
```

Cuando el conjunto de resultados supera el límite por llamada, CloudWatch devuelve una matriz `result` truncada e incluye un mensaje en el campo `warnings`:

```
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [ ... up to 500 series ... ]
    },
    "warnings": [
        "result truncated to the maximum of 500 series; refine the query or use the limit parameter"
    ]
}
```