# Listar CFDIs de retenciones

> `GET https://api.cfdi.express/v1/retenciones` — Lista las constancias de retenciones con filtros por emisor, estatus, UUID, RFC del prestador, ejercicio y mes. Paginación por cursor.

URL de esta página: https://cfdi.express/docs/api/listar-retenciones
Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`)
Header `x-account-id`: indica la cuenta. Si no eres miembro, la respuesta es 403.

Desde la v1.43.0. Cada elemento es un recurso `retencion`, el mismo de [POST /v1/retenciones](https://cfdi.express/docs/api/timbrar-retencion).

Por MCP, `list_retenciones` acepta los mismos filtros.

### Query string

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `limit` | integer | no | Elementos por página. Entre 1 y 100. Default 10. |
| `starting_after` | string | no | Id de la última retención de la página anterior (cursor), mientras has_more sea true. |
| `merchantId` | string | no | Filtra por emisor. |
| `status` | string | no | stamping, stamped, stamp_failed, cancel_pending o cancelled. |
| `uuid` | string | no | Busca por folio fiscal (UUID) del SAT. |
| `receiverRfc` | string | no | RFC de un prestador. Con XEXX010101000 lista a todos los prestadores extranjeros. |
| `ejercicio` | integer | no | Año reportado. |
| `mes` | integer | no | Mes reportado, de 1 a 12. |
| `createdFrom` | string | no | Fecha ISO 8601 mínima de creación. |
| `createdTo` | string | no | Fecha ISO 8601 máxima de creación. |

## Ejemplos

### cURL

```bash
curl -G https://api.cfdi.express/v1/retenciones \
  -H "Authorization: Bearer sk_test_..." \
  --data-urlencode "status=stamped" \
  --data-urlencode "ejercicio=2026" \
  --data-urlencode "mes=9" \
  --data-urlencode "limit=20"
```

## Respuesta

### 200 OK

```json
{
  "object": "list",
  "data": [
    {
      "id": "ret7k3q9x2m4v1t8p6d0n5cb",
      "object": "retencion",
      "livemode": false,
      "status": "stamped",
      "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
      "uuid": "9f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "cveRetenc": "26",
      "ejercicio": 2026,
      "mes": 9,
      "periodicidad": "02",
      "tipoServicio": "05",
      "montoTotOperacion": 1000,
      "montoTotRet": 360,
      "createdAt": "2026-10-01T16:00:08.907Z"
    }
  ],
  "has_more": false
}
```

## Errores

| Status | code | Cuándo aparece |
|---|---|---|
| 401 | `unauthorized` | Falta el header Authorization o la llave es inválida. |
| 429 | `rate_limited` | Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After. |

## Relacionados

- [POST /v1/retenciones](https://cfdi.express/docs/api/timbrar-retencion) — Timbrar retención
- [GET /v1/retenciones/{id}](https://cfdi.express/docs/api/obtener-retencion) — Consultar retención

---

Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express