# Crear una exportación de auditoría

`POST /v1/audit-exports` · permiso `audit-exports:write`

Pone en cola un trabajo que escribe los registros de auditoría coincidentes en un paquete firmado que puede verificar sin confiar en KeenAuth. El trabajo se devuelve con `202 Accepted`; haga seguimiento con [Obtener una exportación de auditoría](get.md) y descargue el archivo con [Descargar una exportación de auditoría](download.md).

Solo las claves de API (secretas o restringidas) pueden crear exportaciones; el trabajo registra la clave como `requested_by`. El entorno se toma de la clave.

## Solicitud

`Idempotency-Key` es obligatorio (de 16 a 64 caracteres, `A-Z a-z 0-9 _ -`). La misma clave con el mismo cuerpo devuelve el primer trabajo con `Idempotent-Replayed: true`; la misma clave con un cuerpo distinto falla con `422 idempotency_key_reuse`. Los SDK y la CLI establecen el encabezado por usted.

Los filtros son los mismos que en [Listar eventos de auditoría](../audit-events/list.md); un campo omitido no filtra. Diferencias:

| Campo | Tipo | Descripción |
|---|---|---|
| `stream` | string | `admin` (predeterminado) o `application`. |
| `from` | RFC 3339 | Límite inferior inclusivo. Por defecto, el inicio de la ventana de retención. No hay límite de 92 días; un paquete contiene como máximo 50 millones de líneas (incluidos los marcadores de posición). |
| `to` | RFC 3339 | Límite superior exclusivo. Por defecto, el momento actual; no puede estar en el futuro. |
| `action`, `category`, `actor_type`, `actor_id`, `target_type`, `target_id`, `org_id`, `outcome`, `request_id`, `correlation_id`, `agent_only` | | Igual que en los filtros de la lista. El filtro `client` de la lista no está disponible aquí; un campo `client` falla con `400 unknown_field`. |
| `include_ip` | boolean | Añade la dirección IP completa y el user agent a los registros con menos de 13 meses. También requiere `audit-events:read_ip`. Predeterminado `false`. |

```json
{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}
```

Como máximo se ejecutan 3 trabajos al mismo tiempo por entorno (1 en los entornos de desarrollo y staging).

## Respuesta

`202 Accepted` y el trabajo con `status` `queued`. `filter` muestra el filtro aplicado con los valores predeterminados de `from` y `to` completados. `recorded_before` es el límite de la instantánea: solo entran en el paquete los registros almacenados antes de él.

```json
{
  "id": "aex_01j9xk3m7q8r2s4t6v8w0y2z4e",
  "status": "queued",
  "filter": {
    "stream": "admin",
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z",
    "action": "user.",
    "category": null,
    "actor_type": null,
    "actor_id": null,
    "target_type": null,
    "target_id": null,
    "org_id": null,
    "outcome": null,
    "request_id": null,
    "correlation_id": null,
    "agent_only": false
  },
  "include_ip": false,
  "record_count": null,
  "file": null,
  "manifest_sha256": null,
  "failure_reason": null,
  "created_at": "2026-10-19T09:00:00Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "recorded_before": "2026-10-19T09:00:00Z",
  "requested_by": {"type": "api_key", "id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d"}
}
```

## Errores

Todos los errores son un cuerpo `application/problem+json` con un `code` estable.

| HTTP | `code` | Cuándo |
|---|---|---|
| 400 | `malformed_request` | Falta `Idempotency-Key` o tiene un formato incorrecto, o el cuerpo no es JSON válido. |
| 400 | `unknown_field` | El cuerpo tiene un campo que no aparece en la lista anterior. |
| 400 | `invalid_filter` | El servicio de auditoría rechazó el filtro, por ejemplo `to` en el futuro. |
| 400 | `range_outside_retention` | `from` o `to` están fuera de la ventana de retención de auditoría de su plan. |
| 422 | `validation_failed` | Un campo no es válido (tipo incorrecto, marca de tiempo errónea, `to` no posterior a `from`, valor de enumeración desconocido, id con formato incorrecto, cadena vacía). |
| 422 | `idempotency_key_reuse` | `Idempotency-Key` se usó con un cuerpo distinto. |
| 401 | `unauthenticated` | La clave de API falta, no es válida o fue revocada. |
| 403 | `insufficient_permissions` | La clave no tiene `audit-exports:write`, usa `include_ip` sin `audit-events:read_ip` (`required_permissions` enumera ambos), o quien llama no es una clave de API. |
| 429 | `rate_limited` | Hay demasiados trabajos en ejecución en este entorno, o se superó el límite de frecuencia; respete `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente más tarde. |

## Ejemplo

```bash
curl https://api.eu.keenauth.com/v1/audit-exports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-07-01T00:00:00Z", "to": "2026-10-01T00:00:00Z", "action": "user."}'
```

```bash
keenauth audit-exports create --from 2026-07-01T00:00:00Z --to 2026-10-01T00:00:00Z --action user.
```

## Datos personales

Este endpoint contiene datos personales: eventos de auditoría. [Datos personales en las API de KeenAuth](/docs/policies/personal-data) describe qué se almacena, cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.