pipefy-observability

Observability

Read the MCP reference or CLI reference for the surface you are using. Load only the relevant reference.

Monitor AI agent and automation execution, usage stats, credit consumption, and export job history.

---

Identifiers reference

Full identifier map: observability identifiers.

Concept	What tools expect	How to obtain
Pipe for AI agent logs	repo_uuid — the pipe UUID	get_pipe with numeric pipe_id; use pipe.uuid.
Automation for logs	automation_id — numeric	get_automations pipe_id=...
Org for usage stats	organization_uuid — UUID or numeric org id	get_organization returns the uuid; a numeric id also works (resolved server-side). Execution-metrics / export take numeric organization_id.

---

Tools

Operation	Read-only	Purpose
get_ai_agent_logs	Yes	Execution history for a specific AI agent.
get_ai_agent_log_details	Yes	Single execution detail for an AI agent log entry.
get_automation_logs	Yes	Execution history for an automation (by automation ID).
get_automation_logs_by_repo	Yes	Automation logs filtered by pipe.
get_agents_usage	Yes	Org-level AI agent execution count and trends.
get_automations_usage	Yes	Org-level automation execution stats.
get_automation_execution_metrics	Yes	Per-automation execution metrics over FIFTEEN_MINUTES, SIXTY_MINUTES, TWELVE_HOURS, or TWENTY_FOUR_HOURS; partial success returns partial_errors for denied ids.
get_ai_credit_usage	Yes	AI credit consumption and remaining balance.
export_automation_jobs	No	Trigger async export of automation job history.
get_automation_jobs_export	Yes	Poll export job status (after export_automation_jobs).
get_automation_jobs_export_csv	Yes	Download finished automation-jobs export as CSV text.

---

Steps — diagnose a failing AI agent

1. Get the pipe UUID (not the numeric pipe ID):

   Operation: get_pipe pipe_id=67890

   Capture pipe.uuid from the response.

2. Fetch recent agent logs:

   Operation: get_ai_agent_logs repo_uuid=<UUID> first=30

3. Identify the failed execution — look for status: failed entries.

4. Check credit usage if the agent stopped unexpectedly:

   Operation: get_ai_credit_usage organization_uuid=123 period="current_month"

5. Fix and re-enable — update the agent config (see pipefy-ai-agents) and toggle status:

   Operation: toggle_ai_agent_status with the agent UUID and active=true (SDK: agent_uuid; MCP: uuid).

---

Steps — export automation history as CSV

1. Trigger the export:

   Operation: export_automation_jobs organization_id=123 period="current_month"

2. Poll for completion:

   Operation: get_automation_jobs_export export_id=<EXPORT_ID>

   Repeat until status is finished or failed.

   A finished export also carries fileUrl, a signed link to the xlsx. It expires 1 hour after the read that returned it, and anyone holding it can download the file until then. When you hand it to the user, say that it expires in 1 hour; for a fresh link, poll again.

3. Fetch CSV text (when finished):

   Operation: get_automation_jobs_export_csv export_id=<EXPORT_ID>

---

Success criteria

• Agent logs show execution timestamps and statuses.
• Credit usage shows remaining balance; no unexpected drops.
• CSV export downloads successfully and contains expected automation history.

Failure modes

• get_ai_agent_logs returns empty: use the pipe UUID (e.g., abc123-...), not the numeric pipe ID. Get UUID from get_pipe.
• get_automation_jobs_export stays in processing: large exports take time. Wait at least 60 seconds between polls. If still processing after several minutes, retry the export trigger.
• Credit usage shows 0 remaining: alert the user — AI features will stop working until credits are replenished. Escalate to the Pipefy admin.

See also

• pipefy-ai-agents — create and configure AI agents.
• pipefy-automations — create and debug automation rules.