Gestor IA — Referência da API

GET /brain/reports brain:read

Listar relatórios do Gestor IA

Os relatórios da conta, do mais novo para o mais antigo: diários, checagens da tarde, análises pedidas e resumos semanais. pending_actions diz quantas ações esperam decisão. Pagine com cursor (meta.next_cursor).

Parâmetros

limit	integer	Itens por página, de 1 a 50 (padrão 15).
cursor	string	meta.next_cursor da página anterior.

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/brain/reports" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": [
        {
            "id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
            "kind": "daily",
            "kind_label": "Relatório diário",
            "mode": "manual",
            "status": "pending_review",
            "status_label": "Aguardando aprovação",
            "health": "good",
            "health_label": "Saudável",
            "report_date": "2026-10-28",
            "period": {
                "from": "2026-10-21",
                "to": "2026-10-27"
            },
            "diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
            "yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
            "yesterday": {
                "spend": 312.5,
                "conversions": 24
            },
            "highlights": [
                "CPA 12% abaixo da meta"
            ],
            "error": null,
            "can_decide": true,
            "started_at": "2026-10-28T09:00:02+00:00",
            "generated_at": "2026-10-28T09:01:40+00:00",
            "expires_at": "2026-10-30T09:01:40+00:00",
            "reviewed_at": null,
            "created_at": "2026-10-28T09:00:00+00:00",
            "links": {
                "panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
            },
            "pending_actions": 1
        }
    ],
    "meta": {
        "per_page": 15,
        "next_cursor": null,
        "prev_cursor": null
    }
}

Erros: validation_failed

GET /brain/reports/{id} brain:read

Consultar relatório

Um relatório com o diagnóstico e as ações. Em actions, kind action se aprova ou recusa (pausar, ativar, mudar verba, realocar); kind suggestion é só para ler (campanha nova, trocar criativo, corrigir rastreamento, esperar). As duas metades de uma realocação têm o mesmo group_key e seguem juntas. Enquanto status for generating, consulte de novo (ou espere o webhook brain.report_ready).

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/brain/reports/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "kind": "daily",
        "kind_label": "Relatório diário",
        "mode": "manual",
        "status": "pending_review",
        "status_label": "Aguardando aprovação",
        "health": "good",
        "health_label": "Saudável",
        "report_date": "2026-10-28",
        "period": {
            "from": "2026-10-21",
            "to": "2026-10-27"
        },
        "diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
        "yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
        "yesterday": {
            "spend": 312.5,
            "conversions": 24
        },
        "highlights": [
            "CPA 12% abaixo da meta"
        ],
        "error": null,
        "can_decide": true,
        "started_at": "2026-10-28T09:00:02+00:00",
        "generated_at": "2026-10-28T09:01:40+00:00",
        "expires_at": "2026-10-30T09:01:40+00:00",
        "reviewed_at": null,
        "created_at": "2026-10-28T09:00:00+00:00",
        "links": {
            "panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
        },
        "can_retry": false,
        "actions": [
            {
                "id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
                "report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
                "type": "update_campaign_budget",
                "type_label": "Mudar orçamento da campanha",
                "kind": "action",
                "summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
                "status": "proposed",
                "status_label": "Aguardando decisão",
                "target": {
                    "type": "campaign",
                    "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                    "name": "Promoção de outubro"
                },
                "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                "params": {
                    "budget_cents": 6500
                },
                "before": {
                    "budget_cents": 5000
                },
                "after": null,
                "reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
                "expected_impact": "+25% de conversões mantendo o CPA.",
                "confidence": "high",
                "priority": 1,
                "is_emergency": false,
                "guard_notes": null,
                "group_key": null,
                "can_decide": true,
                "can_rollback": false,
                "rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
                "decided_at": null,
                "executor": null,
                "executed_at": null,
                "error": null,
                "rolled_back_at": null,
                "evaluation": null
            }
        ]
    }
}

Erros: not_found

POST /brain/reports brain:manage

Pedir uma análise agora

O "Analisar agora" do painel: abre o relatório (status generating) e a IA analisa a conta pela fila em 1 a 3 minutos. Uma por conta por hora (a que falhou não conta). Responde 202 com Location; acompanhe pelo GET ou pelo webhook brain.report_ready.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/brain/reports" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 202

HTTP 202

{
    "data": {
        "id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "kind": "manual",
        "kind_label": "Análise pedida",
        "mode": "manual",
        "status": "generating",
        "status_label": "Analisando",
        "health": null,
        "health_label": null,
        "report_date": "2026-10-28",
        "period": {
            "from": "2026-10-21",
            "to": "2026-10-27"
        },
        "diagnosis": null,
        "yesterday_summary": null,
        "yesterday": null,
        "highlights": null,
        "error": null,
        "can_decide": false,
        "started_at": "2026-10-28T09:00:02+00:00",
        "generated_at": null,
        "expires_at": null,
        "reviewed_at": null,
        "created_at": "2026-10-28T09:00:00+00:00",
        "links": {
            "panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
        }
    }
}

Erros: ad_account_not_linked, brain_disabled, analysis_in_progress, analysis_too_soon

POST /brain/reports/{id}/retry brain:manage

Refazer análise que falhou

Refaz a análise de um relatório com status failed (só a mais recente da conta; can_retry diz se dá). Abre um relatório novo e responde 202.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/brain/reports/{id}/retry" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 202

HTTP 202

{
    "data": {
        "id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "kind": "daily",
        "kind_label": "Relatório diário",
        "mode": "manual",
        "status": "generating",
        "status_label": "Analisando",
        "health": "good",
        "health_label": "Saudável",
        "report_date": "2026-10-28",
        "period": {
            "from": "2026-10-21",
            "to": "2026-10-27"
        },
        "diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
        "yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
        "yesterday": {
            "spend": 312.5,
            "conversions": 24
        },
        "highlights": [
            "CPA 12% abaixo da meta"
        ],
        "error": null,
        "can_decide": true,
        "started_at": "2026-10-28T09:00:02+00:00",
        "generated_at": "2026-10-28T09:01:40+00:00",
        "expires_at": "2026-10-30T09:01:40+00:00",
        "reviewed_at": null,
        "created_at": "2026-10-28T09:00:00+00:00",
        "links": {
            "panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
        }
    }
}

Erros: not_found, report_not_retryable, brain_disabled, analysis_in_progress

POST /brain/reports/{id}/approve brain:manage

Aprovar todas as ações

Aprova as ações ainda pendentes do relatório e manda aplicar na Meta pela fila (as já decididas ficam como estão). O relatório espera decisão por 48 horas; depois, expira.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/brain/reports/{id}/approve" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "kind": "daily",
        "kind_label": "Relatório diário",
        "mode": "manual",
        "status": "approved",
        "status_label": "Aprovado",
        "health": "good",
        "health_label": "Saudável",
        "report_date": "2026-10-28",
        "period": {
            "from": "2026-10-21",
            "to": "2026-10-27"
        },
        "diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
        "yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
        "yesterday": {
            "spend": 312.5,
            "conversions": 24
        },
        "highlights": [
            "CPA 12% abaixo da meta"
        ],
        "error": null,
        "can_decide": false,
        "started_at": "2026-10-28T09:00:02+00:00",
        "generated_at": "2026-10-28T09:01:40+00:00",
        "expires_at": "2026-10-30T09:01:40+00:00",
        "reviewed_at": null,
        "created_at": "2026-10-28T09:00:00+00:00",
        "links": {
            "panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
        },
        "can_retry": false,
        "actions": [
            {
                "id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
                "report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
                "type": "update_campaign_budget",
                "type_label": "Mudar orçamento da campanha",
                "kind": "action",
                "summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
                "status": "queued",
                "status_label": "Na fila",
                "target": {
                    "type": "campaign",
                    "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                    "name": "Promoção de outubro"
                },
                "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                "params": {
                    "budget_cents": 6500
                },
                "before": {
                    "budget_cents": 5000
                },
                "after": null,
                "reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
                "expected_impact": "+25% de conversões mantendo o CPA.",
                "confidence": "high",
                "priority": 1,
                "is_emergency": false,
                "guard_notes": null,
                "group_key": null,
                "can_decide": false,
                "can_rollback": false,
                "rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
                "decided_at": null,
                "executor": null,
                "executed_at": null,
                "error": null,
                "rolled_back_at": null,
                "evaluation": null
            }
        ]
    }
}

Erros: not_found, report_not_decidable

POST /brain/reports/{id}/reject brain:manage

Recusar todas as ações

Recusa as ações ainda pendentes do relatório. Nada muda na Meta.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/brain/reports/{id}/reject" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "kind": "daily",
        "kind_label": "Relatório diário",
        "mode": "manual",
        "status": "rejected",
        "status_label": "Recusado",
        "health": "good",
        "health_label": "Saudável",
        "report_date": "2026-10-28",
        "period": {
            "from": "2026-10-21",
            "to": "2026-10-27"
        },
        "diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
        "yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
        "yesterday": {
            "spend": 312.5,
            "conversions": 24
        },
        "highlights": [
            "CPA 12% abaixo da meta"
        ],
        "error": null,
        "can_decide": false,
        "started_at": "2026-10-28T09:00:02+00:00",
        "generated_at": "2026-10-28T09:01:40+00:00",
        "expires_at": "2026-10-30T09:01:40+00:00",
        "reviewed_at": null,
        "created_at": "2026-10-28T09:00:00+00:00",
        "links": {
            "panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
        },
        "can_retry": false,
        "actions": [
            {
                "id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
                "report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
                "type": "update_campaign_budget",
                "type_label": "Mudar orçamento da campanha",
                "kind": "action",
                "summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
                "status": "rejected",
                "status_label": "Recusada",
                "target": {
                    "type": "campaign",
                    "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                    "name": "Promoção de outubro"
                },
                "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                "params": {
                    "budget_cents": 6500
                },
                "before": {
                    "budget_cents": 5000
                },
                "after": null,
                "reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
                "expected_impact": "+25% de conversões mantendo o CPA.",
                "confidence": "high",
                "priority": 1,
                "is_emergency": false,
                "guard_notes": null,
                "group_key": null,
                "can_decide": false,
                "can_rollback": false,
                "rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
                "decided_at": null,
                "executor": null,
                "executed_at": null,
                "error": null,
                "rolled_back_at": null,
                "evaluation": null
            }
        ]
    }
}

Erros: not_found, report_not_decidable

POST /brain/actions/{id}/approve brain:manage

Aprovar uma ação

Aprova a ação e manda aplicar na Meta pela fila. Numa realocação, a aplicação só sai quando as duas metades (mesmo group_key) estão aprovadas.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/brain/actions/{id}/approve" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
        "report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "type": "update_campaign_budget",
        "type_label": "Mudar orçamento da campanha",
        "kind": "action",
        "summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
        "status": "queued",
        "status_label": "Na fila",
        "target": {
            "type": "campaign",
            "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
            "name": "Promoção de outubro"
        },
        "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
        "params": {
            "budget_cents": 6500
        },
        "before": {
            "budget_cents": 5000
        },
        "after": null,
        "reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
        "expected_impact": "+25% de conversões mantendo o CPA.",
        "confidence": "high",
        "priority": 1,
        "is_emergency": false,
        "guard_notes": null,
        "group_key": null,
        "can_decide": false,
        "can_rollback": false,
        "rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
        "decided_at": "2026-10-28T10:15:00+00:00",
        "executor": "user",
        "executed_at": null,
        "error": null,
        "rolled_back_at": null,
        "evaluation": null
    }
}

Erros: not_found, action_not_decidable, report_not_decidable

POST /brain/actions/{id}/reject brain:manage

Recusar uma ação

Recusa a ação; numa realocação, a outra metade é recusada junto.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/brain/actions/{id}/reject" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
        "report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "type": "update_campaign_budget",
        "type_label": "Mudar orçamento da campanha",
        "kind": "action",
        "summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
        "status": "rejected",
        "status_label": "Recusada",
        "target": {
            "type": "campaign",
            "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
            "name": "Promoção de outubro"
        },
        "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
        "params": {
            "budget_cents": 6500
        },
        "before": {
            "budget_cents": 5000
        },
        "after": null,
        "reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
        "expected_impact": "+25% de conversões mantendo o CPA.",
        "confidence": "high",
        "priority": 1,
        "is_emergency": false,
        "guard_notes": null,
        "group_key": null,
        "can_decide": false,
        "can_rollback": false,
        "rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
        "decided_at": "2026-10-28T10:15:00+00:00",
        "executor": null,
        "executed_at": null,
        "error": null,
        "rolled_back_at": null,
        "evaluation": null
    }
}

Erros: not_found, action_not_decidable, report_not_decidable

POST /brain/actions/{id}/rollback brain:manage

Desfazer uma ação aplicada

Volta ao estado anterior (verba ou status) uma ação aplicada há menos de 24 horas, se ninguém mexeu no alvo depois. can_rollback e rollback_blocker dizem se dá e por quê.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/brain/actions/{id}/rollback" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
        "report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
        "type": "update_campaign_budget",
        "type_label": "Mudar orçamento da campanha",
        "kind": "action",
        "summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
        "status": "executed",
        "status_label": "Aplicada",
        "target": {
            "type": "campaign",
            "id": "01jby0q4c8m2d6t9v3k7w5r1xa",
            "name": "Promoção de outubro"
        },
        "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
        "params": {
            "budget_cents": 6500
        },
        "before": {
            "budget_cents": 5000
        },
        "after": null,
        "reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
        "expected_impact": "+25% de conversões mantendo o CPA.",
        "confidence": "high",
        "priority": 1,
        "is_emergency": false,
        "guard_notes": null,
        "group_key": null,
        "can_decide": false,
        "can_rollback": false,
        "rollback_blocker": "Esta ação já foi desfeita.",
        "decided_at": null,
        "executor": null,
        "executed_at": null,
        "error": null,
        "rolled_back_at": "2026-10-28T12:00:00+00:00",
        "evaluation": null
    }
}

Erros: not_found, rollback_unavailable, operation_failed