Skip to main content
The inspection API gives you read-only access to everything MirrorNeuron persists about running and completed jobs: job records, per-agent snapshots, append-only event histories, executor pool capacity, and enriched summaries that combine all of the above. All state is backed by Redis, so these calls are safe to make from any connected node — including from external scripts and automation tools that do not participate in the BEAM cluster.

​
MirrorNeuron.inspect_job/1

Reads the persisted job record for a single job directly from Redis. 
MirrorNeuron.inspect_job(job_id)
​
job_id
String.t()
required
The unique job identifier returned by run_manifest/2.

​
Return values

{:ok, job_map}
​
job_map
map
The full persisted job record.

​
Example

{:ok, job} = MirrorNeuron.inspect_job("prime_sweep_40_workers-abc123")

IO.puts("Status: #{job["status"]}")
IO.puts("Submitted: #{job["submitted_at"]}")
IO.inspect(job["root_agent_ids"])
Example job record: 
{
  "job_id": "prime_sweep_40_workers-abc123",
  "graph_id": "prime_sweep_40_workers",
  "job_name": null,
  "status": "completed",
  "submitted_at": "2026-03-28T11:00:00.000Z",
  "updated_at": "2026-03-28T11:00:12.000Z",
  "placement_policy": "local",
  "recovery_policy": "local_restart",
  "root_agent_ids": ["dispatcher"],
  "result": {},
  "manifest_ref": {
    "graph_id": "prime_sweep_40_workers",
    "manifest_version": "1.0",
    "manifest_path": "/abs/path/manifest.json",
    "job_path": "/abs/path/job-folder"
  }
}

​
MirrorNeuron.inspect_agents/1

Reads persisted agent snapshots for all agents in a job. Each snapshot reflects the agent’s last written state — useful for debugging stalled workflows, inspecting message throughput, and verifying node placement. 
MirrorNeuron.inspect_agents(job_id)
​
job_id
String.t()
required
The unique job identifier.

​
Return values

{:ok, [agent_snapshot]}
​
agent_snapshot
map
Per-agent state snapshot.

​
Example

{:ok, agents} = MirrorNeuron.inspect_agents("prime_sweep_40_workers-abc123")

Enum.each(agents, fn agent ->
  IO.puts("#{agent["agent_id"]} — #{agent["agent_type"]} — #{agent["processed_messages"]} msgs processed")
end)
Example agent snapshot: 
{
  "agent_id": "prime_worker_0001",
  "agent_type": "executor",
  "type": "map",
  "assigned_node": "mn1@192.168.4.183",
  "processed_messages": 1,
  "mailbox_depth": 0,
  "current_state": {
    "runs": 1,
    "last_result": {
      "sandbox_name": "mirror-neuron-job-abc123",
      "lease": {
        "lease_id": "lease-xyz",
        "pool": "default",
        "slots": 1
      }
    }
  },
  "metadata": {
    "paused": false,
    "outbound_edges": ["aggregator"]
  }
}

​
MirrorNeuron.events/1

Reads the append-only event list for a job from Redis. Events are written by the runtime as agents process messages, sandboxes complete, and job status transitions occur. The list is ordered chronologically. 
MirrorNeuron.events(job_id)
​
job_id
String.t()
required
The unique job identifier.

​
Return values

{:ok, [event]}
​
event
map
A single event entry.

​
Example

{:ok, events} = MirrorNeuron.events("prime_sweep_40_workers-abc123")

events
|> Enum.filter(&(&1["type"] == "sandbox_job_completed"))
|> Enum.each(fn e ->
  IO.puts("[#{e["timestamp"]}] #{e["agent_id"]} — exit #{e["payload"]["exit_code"]}")
end)
Example event: 
{
  "timestamp": "2026-03-28T11:00:04.000Z",
  "type": "sandbox_job_completed",
  "agent_id": "prime_worker_0001",
  "payload": {
    "sandbox_name": "mirror-neuron-job-abc123",
    "exit_code": 0,
    "pool": "default"
  }
}
Events are also published to a Redis Pub/Sub channel at mirror_neuron:channel:events:<job_id>. This channel is the best foundation for building live dashboards that stream events as they happen.

​
MirrorNeuron.inspect_nodes/0

Returns a list of node summaries for every node visible to the cluster, including executor pool capacity statistics for each node. 
MirrorNeuron.inspect_nodes()
This function takes no arguments.

​
Return value

Returns a list of node summary maps directly (not wrapped in {:ok, ...}). 
[%{...}]
​
node_summary
map
Per-node summary.

​
Example

nodes = MirrorNeuron.inspect_nodes()

Enum.each(nodes, fn node ->
  pool = get_in(node, ["executor_pools", "default"])
  IO.puts("#{node["name"]} — #{pool["in_use"]}/#{pool["capacity"]} slots in use")
end)
Example response: 
[
  {
    "name": "mn1@192.168.4.183",
    "connected_nodes": ["mn1@192.168.4.183", "mn2@192.168.4.35"],
    "self?": true,
    "scheduler_hint": "cluster_member",
    "executor_pools": {
      "default": {
        "capacity": 2,
        "available": 1,
        "in_use": 1,
        "queued": 0,
        "active": 1
      }
    }
  }
]

​
MirrorNeuron.list_jobs/1

Returns enriched job summaries for all known jobs. This is the preferred function for building dashboards and operational scripts — it layers additional computed fields on top of the raw job record. 
MirrorNeuron.list_jobs(opts \\ [])
​
opts
keyword list
Filtering options.

​
Return values

{:ok, [job_summary]}
​
job_summary
map
Enriched job record with additional computed fields beyond what inspect_job/1 returns.

​
Example

{:ok, jobs} = MirrorNeuron.list_jobs(include_terminal: false, limit: 10)

Enum.each(jobs, fn job ->
  IO.puts("#{job["job_id"]} — #{job["status"]} — #{job["active_executors"]} active executors")
end)
Prefer list_jobs/1 over calling inspect_job/1 in a loop. It is implemented in the stable monitor boundary and is designed to remain consistent across runtime versions.

​
MirrorNeuron.job_details/2

Returns the full monitor detail view for a single job. This is the same data that powers the mirror_neuron monitor terminal UI and is the richest single-call inspection function available. 
MirrorNeuron.job_details(job_id, opts \\ [])
​
job_id
String.t()
required
The unique job identifier.
​
opts
keyword list
View options.

​
Return values

{:ok, details}
​
details
map
Full job detail view.

​
Example

{:ok, details} = MirrorNeuron.job_details("prime_sweep_40_workers-abc123", event_limit: 50)

IO.puts("Job status: #{details["job"]["status"]}")
IO.puts("Active executors: #{details["summary"]["active_executors"]}")

Enum.each(details["agents"], fn agent ->
  IO.puts("  #{agent["agent_id"]}: running=#{agent["running?"]}, paused=#{agent["paused?"]}")
end)

​
MirrorNeuron.cluster_overview/1

Returns a combined snapshot of all cluster nodes and all known jobs in a single call. This is the starting point for cluster-wide dashboards and monitoring scripts. 
MirrorNeuron.cluster_overview(opts \\ [])
​
opts
keyword list
Options forwarded to the internal list_jobs/1 call. Accepts the same limit and include_terminal options.

​
Return values

{:ok, %{"nodes" => [...], "jobs" => [...]}}
​
nodes
map[]
List of node summaries. Same shape as inspect_nodes/0 output.
​
jobs
map[]
List of enriched job summaries. Same shape as list_jobs/1 output.

​
Example

{:ok, overview} = MirrorNeuron.cluster_overview(include_terminal: false)

IO.puts("Nodes: #{length(overview["nodes"])}")
IO.puts("Active jobs: #{length(overview["jobs"])}")

Enum.each(overview["nodes"], fn node ->
  pool = get_in(node, ["executor_pools", "default"])
  IO.puts("  #{node["name"]}: #{pool["in_use"]}/#{pool["capacity"]} slots")
end)
cluster_overview/1 is equivalent to calling inspect_nodes/0 and list_jobs/1 separately and merging the results. Use it when you need both views together to reduce round trips.