# Consultar gasto diario de la cuenta publicitaria de Meta
> Lee el gasto y la entrega DIARIOS de la cuenta publicitaria de Meta de esta conexión, YA sincronizados: gasto, impresiones, alcance y clics de cada día, con su moneda y la zona horaria de la cuenta.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `meta_ads.gasto_cuenta.consultar` |
| **Nombre MCP** | `meta_ads__gasto_cuenta__consultar` |
| **Conector** | `meta_ads` |
| **Plano** | `action` |
| **Lee el alcance** | `gasto` (debe estar habilitado en la conexión) |
| **Scope (permiso)** | `meta_ads:read` |
| **Auth** | `none` |
| **Versión** | `1` |
| **Sensible** | sí |
| **Deprecado** | no |
| **Comportamiento** | readOnly=true, destructive=false, idempotent=true, openWorld=false |
> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST y campo `connectionId` en el `execute` de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de [`conexiones.estado.consultar`](/docs/referencia/conexiones/estado-consultar).
## Qué hace [#qué-hace]
Es el total de la cuenta: no lo sumes con las filas por campaña. Lectura pura: NO contacta a Meta ni dispara una sincronización. Revisa 'cobertura' antes de concluir que no hubo gasto. Las cifras son las que Meta informa en Insights: el gasto es estimado y NO equivale a facturas, cobros ni impuestos. No mezcles monedas. Para traer datos nuevos usa 'meta\_ads.conexion.sincronizar'. Pagina con 'cursor'.
## Entrada [#entrada]
| Campo | Tipo | Requerido | Descripción |
| -------- | ---------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `desde` | string `^\d{4}-\d{2}-\d{2}$` | no | Primer día (AAAA-MM-DD, día calendario en la zona horaria de la cuenta publicitaria). Omítelo para no filtrar. |
| `hasta` | string `^\d{4}-\d{2}-\d{2}$` | no | Último día, incluido (AAAA-MM-DD, día calendario en la zona horaria de la cuenta publicitaria). Omítelo para no filtrar. |
| `cursor` | string | no | Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página. |
| `limit` | entero 1-500 | no · default `100` | Cuántas filas trae la página, entre 1 y 500. Por omisión, 100. |
JSON Schema de entrada
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"desde": {
"description": "Primer día (AAAA-MM-DD, día calendario en la zona horaria de la cuenta publicitaria). Omítelo para no filtrar.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"hasta": {
"description": "Último día, incluido (AAAA-MM-DD, día calendario en la zona horaria de la cuenta publicitaria). Omítelo para no filtrar.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"cursor": {
"description": "Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página.",
"type": "string"
},
"limit": {
"default": 100,
"description": "Cuántas filas trae la página, entre 1 y 500. Por omisión, 100.",
"type": "integer",
"minimum": 1,
"maximum": 500
}
}
}
```
## Ejemplo [#ejemplo]
```bash title="curl"
curl -X POST https://connect.emisso.ai/api/v1/tools/meta_ads.gasto_cuenta.consultar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"desde":"2026-10-01","hasta":"2026-10-20"}}'
```
```json title="MCP · meta-tool execute"
{
"tool": "meta_ads.gasto_cuenta.consultar",
"params": {
"desde": "2026-10-01",
"hasta": "2026-10-20"
},
"connectionId": "conn_9tKfR2mQx4Vb"
}
```
**Salida esperada (200):**
```json
{
"data": {
"cuenta": {
"cuentaId": "1234567890123456",
"moneda": "CLP",
"zonaHoraria": "America/Santiago"
},
"filas": [
{
"fecha": "2026-10-19",
"moneda": "CLP",
"zonaHoraria": "America/Santiago",
"gasto": "48250",
"impresiones": 61234,
"alcance": 30211,
"clics": 1402,
"clicsEnlace": 988,
"diaCerrado": true,
"versionApi": "v26.0",
"sincronizadoEn": "2026-10-20T16:00:02.000Z"
}
],
"cobertura": {
"desde": "2025-09-21",
"hasta": "2026-10-20",
"completa": true,
"diasSinLeer": [],
"pendiente": null,
"sincronizadoEn": "2026-10-20T16:00:02.000Z"
},
"cursor": null
},
"meta": {
"request_id": "req_…",
"tool_id": "meta_ads.gasto_cuenta.consultar",
"plane": "action",
"latency_ms": 24,
"audit_status": "recorded"
}
}
```
> El gasto viene como texto decimal en la moneda de la cuenta. Un día sin fila dentro de la cobertura es un día sin entrega.
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | |
| -------------------------------- | --------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cuenta` | objeto | sí | La cuenta publicitaria fijada a esta conexión. Una conexión lee UNA sola cuenta publicitaria. | |
| `cuenta.cuentaId` | string | null | sí | El id de la cuenta publicitaria en Meta, sin el prefijo 'act\_', como texto. null si la conexión todavía no sincronizó. |
| `cuenta.moneda` | string | null | sí | La moneda de la cuenta (ISO 4217) en la última sincronización. Cada fila trae además la suya. |
| `cuenta.zonaHoraria` | string | null | sí | La zona horaria IANA de la cuenta (por ejemplo 'America/Santiago'): en ella corta Meta los días. |
| `filas` | lista de objeto | sí | Un día por fila, del más reciente al más antiguo: el total de la cuenta publicitaria ese día. | |
| `filas[].fecha` | string | sí | El día (AAAA-MM-DD) en la zona horaria de 'zonaHoraria', la de la cuenta publicitaria. No es un día de Chile si la cuenta usa otra zona. | |
| `filas[].moneda` | string | sí | La moneda del gasto (ISO 4217, la de la cuenta publicitaria). Nunca sumes gastos de monedas distintas. | |
| `filas[].zonaHoraria` | string | sí | La zona horaria IANA con que Meta cortó este día. | |
| `filas[].gasto` | string | sí | Gasto estimado del día según Meta, decimal en texto en 'moneda' (por ejemplo "15990" o "12.34"). Es una métrica de entrega publicitaria, NO un comprobante: no es lo facturado ni lo cobrado, y no incluye impuestos. | |
| `filas[].impresiones` | entero | sí | Veces que se mostraron los anuncios ese día. | |
| `filas[].alcance` | entero | null | sí | Personas únicas (cuentas del Centro de cuentas) que vieron los anuncios ese día, estimado por Meta. NO se suma entre días ni entre campañas: una persona puede repetirse. null si Meta no lo informó; null no es cero. |
| `filas[].clics` | entero | null | sí | Clics de todo tipo según Meta. null si no lo informó. |
| `filas[].clicsEnlace` | entero | null | sí | Clics en el enlace del anuncio según Meta (inline\_link\_clicks). Es una métrica de interacción, no una conversión ni una venta. null si no lo informó. |
| `filas[].diaCerrado` | booleano | sí | false si al leerlo el día todavía no terminaba en la zona de la cuenta: sus cifras pueden crecer. | |
| `filas[].versionApi` | string | sí | La versión de la Marketing API con que se leyó la fila (por ejemplo 'v26.0'). | |
| `filas[].sincronizadoEn` | string | sí | Cuándo guardó Connect esta versión de la fila (ISO 8601, UTC). Meta puede corregir días de hasta 28 días atrás; la relectura reemplaza la fila. | |
| `cobertura` | objeto | sí | Qué cubre lo guardado. Dentro de \[desde, hasta], un día SIN fila significa que Meta no informó entrega ese día (gasto cero), salvo que caiga en 'diasSinLeer'. Fuera de la cobertura, el gasto es desconocido. | |
| `cobertura.desde` | string | null | sí | Primer día (AAAA-MM-DD, zona de la cuenta) desde el que están guardados los dos niveles. null si nunca se sincronizó. |
| `cobertura.hasta` | string | null | sí | Último día leído (AAAA-MM-DD). Puede ser hoy: las filas con 'diaCerrado' en false todavía pueden crecer. |
| `cobertura.completa` | booleano | sí | true sólo si el histórico llegó al horizonte del conector (\~13 meses), no quedó ningún tramo sin leer y la última sincronización no quedó a medias. En false, una lista vacía NO prueba que no hubo gasto: dilo así. | |
| `cobertura.diasSinLeer` | lista de objeto | sí | Tramos dentro de la cobertura que no se pudieron leer: ahí el gasto es DESCONOCIDO, no cero. | |
| `cobertura.diasSinLeer[].desde` | string | sí | Primer día del tramo (AAAA-MM-DD). | |
| `cobertura.diasSinLeer[].hasta` | string | sí | Último día del tramo (AAAA-MM-DD). | |
| `cobertura.diasSinLeer[].motivo` | string | sí | Por qué no se leyó: 'demasiados\_datos', 'datos\_ilegibles' o 'agrupada'. | |
| `cobertura.pendiente` | `"presupuesto"` · `"error_transitorio"` | null | sí | Si la última sincronización terminó con trabajo pendiente: 'presupuesto' (quedó historia por leer) o 'error\_transitorio' (Meta limitó o no respondió). null si terminó todo lo que tenía. |
| `cobertura.sincronizadoEn` | string | null | sí | Cuándo terminó la última sincronización que guardó datos (ISO 8601, UTC). null si nunca. |
| `cursor` | string | null | sí | Puntero a la página siguiente. Si viene distinto de null hay más filas: vuelve a llamar reenviándolo tal cual en 'cursor'. Un null significa que no queda nada por traer. |
JSON Schema de salida
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"cuenta": {
"type": "object",
"properties": {
"cuentaId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El id de la cuenta publicitaria en Meta, sin el prefijo 'act_', como texto. null si la conexión todavía no sincronizó."
},
"moneda": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La moneda de la cuenta (ISO 4217) en la última sincronización. Cada fila trae además la suya."
},
"zonaHoraria": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La zona horaria IANA de la cuenta (por ejemplo 'America/Santiago'): en ella corta Meta los días."
}
},
"required": [
"cuentaId",
"moneda",
"zonaHoraria"
],
"additionalProperties": false,
"description": "La cuenta publicitaria fijada a esta conexión. Una conexión lee UNA sola cuenta publicitaria."
},
"filas": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fecha": {
"type": "string",
"description": "El día (AAAA-MM-DD) en la zona horaria de 'zonaHoraria', la de la cuenta publicitaria. No es un día de Chile si la cuenta usa otra zona."
},
"moneda": {
"type": "string",
"description": "La moneda del gasto (ISO 4217, la de la cuenta publicitaria). Nunca sumes gastos de monedas distintas."
},
"zonaHoraria": {
"type": "string",
"description": "La zona horaria IANA con que Meta cortó este día."
},
"gasto": {
"type": "string",
"description": "Gasto estimado del día según Meta, decimal en texto en 'moneda' (por ejemplo \"15990\" o \"12.34\"). Es una métrica de entrega publicitaria, NO un comprobante: no es lo facturado ni lo cobrado, y no incluye impuestos."
},
"impresiones": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Veces que se mostraron los anuncios ese día."
},
"alcance": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "Personas únicas (cuentas del Centro de cuentas) que vieron los anuncios ese día, estimado por Meta. NO se suma entre días ni entre campañas: una persona puede repetirse. null si Meta no lo informó; null no es cero."
},
"clics": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "Clics de todo tipo según Meta. null si no lo informó."
},
"clicsEnlace": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "Clics en el enlace del anuncio según Meta (inline_link_clicks). Es una métrica de interacción, no una conversión ni una venta. null si no lo informó."
},
"diaCerrado": {
"type": "boolean",
"description": "false si al leerlo el día todavía no terminaba en la zona de la cuenta: sus cifras pueden crecer."
},
"versionApi": {
"type": "string",
"description": "La versión de la Marketing API con que se leyó la fila (por ejemplo 'v26.0')."
},
"sincronizadoEn": {
"type": "string",
"description": "Cuándo guardó Connect esta versión de la fila (ISO 8601, UTC). Meta puede corregir días de hasta 28 días atrás; la relectura reemplaza la fila."
}
},
"required": [
"fecha",
"moneda",
"zonaHoraria",
"gasto",
"impresiones",
"alcance",
"clics",
"clicsEnlace",
"diaCerrado",
"versionApi",
"sincronizadoEn"
],
"additionalProperties": false
},
"description": "Un día por fila, del más reciente al más antiguo: el total de la cuenta publicitaria ese día."
},
"cobertura": {
"type": "object",
"properties": {
"desde": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primer día (AAAA-MM-DD, zona de la cuenta) desde el que están guardados los dos niveles. null si nunca se sincronizó."
},
"hasta": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Último día leído (AAAA-MM-DD). Puede ser hoy: las filas con 'diaCerrado' en false todavía pueden crecer."
},
"completa": {
"type": "boolean",
"description": "true sólo si el histórico llegó al horizonte del conector (~13 meses), no quedó ningún tramo sin leer y la última sincronización no quedó a medias. En false, una lista vacía NO prueba que no hubo gasto: dilo así."
},
"diasSinLeer": {
"type": "array",
"items": {
"type": "object",
"properties": {
"desde": {
"type": "string",
"description": "Primer día del tramo (AAAA-MM-DD)."
},
"hasta": {
"type": "string",
"description": "Último día del tramo (AAAA-MM-DD)."
},
"motivo": {
"type": "string",
"description": "Por qué no se leyó: 'demasiados_datos', 'datos_ilegibles' o 'agrupada'."
}
},
"required": [
"desde",
"hasta",
"motivo"
],
"additionalProperties": false
},
"description": "Tramos dentro de la cobertura que no se pudieron leer: ahí el gasto es DESCONOCIDO, no cero."
},
"pendiente": {
"anyOf": [
{
"type": "string",
"enum": [
"presupuesto",
"error_transitorio"
]
},
{
"type": "null"
}
],
"description": "Si la última sincronización terminó con trabajo pendiente: 'presupuesto' (quedó historia por leer) o 'error_transitorio' (Meta limitó o no respondió). null si terminó todo lo que tenía."
},
"sincronizadoEn": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cuándo terminó la última sincronización que guardó datos (ISO 8601, UTC). null si nunca."
}
},
"required": [
"desde",
"hasta",
"completa",
"diasSinLeer",
"pendiente",
"sincronizadoEn"
],
"additionalProperties": false,
"description": "Qué cubre lo guardado. Dentro de [desde, hasta], un día SIN fila significa que Meta no informó entrega ese día (gasto cero), salvo que caiga en 'diasSinLeer'. Fuera de la cobertura, el gasto es desconocido."
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Puntero a la página siguiente. Si viene distinto de null hay más filas: vuelve a llamar reenviándolo tal cual en 'cursor'. Un null significa que no queda nada por traer."
}
},
"required": [
"cuenta",
"filas",
"cobertura",
"cursor"
],
"additionalProperties": false
}
```
## Errores de esta tool [#errores-de-esta-tool]
| Código | HTTP | Reintentable | Qué hacer |
| ---------------------- | ---- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `connection_disabled` | 403 | no | Reactívala en /connections o usa otra conexión del mismo sistema. |
| `connection_not_found` | 404 | no | Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada. |
| `alcance_not_enabled` | 403 | no | Habilita el alcance en /connections o quítalo del input de la sincronización. |
Toda llamada puede devolver además los códigos transversales (`validation_error`, `unauthorized`, `scope_not_granted`, `rate_limited`, entre otros): el detalle vive en el [catálogo de errores](/docs/referencia/errores).
## Próximos pasos [#próximos-pasos]
* [`meta_ads.conexion.sincronizar`](/docs/referencia/meta_ads/conexion-sincronizar): la tool que escribe los datos que esta lectura devuelve.
* [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): por qué leer datos reales son dos pasos.