---
title: "Inspect Objective"
method: POST
path: "/api/facade/inspect_objective"
tags: ["facade"]
---

# Inspect Objective

`POST /api/facade/inspect_objective`

## Request

- Base URL: `https://api.vruum.ai`
- URL: `https://api.vruum.ai/api/facade/inspect_objective`
- Auth: `HTTPBearer` (a scheme the document does not define)

Read one objective's planning state: setup, audience, forecast, and sourcing. Read-only.

These actions write no records. Every action takes id = objective UUID.
- objective_agent_options: read current runtime start eligibility, objective versions and eligible sender mailboxes before delegation. A missing business plan is not a meeting-pursuit blocker. No work is started.
- objective_agent_work: inspect the latest meeting or content job, exact reviews, publication/delivery waits and due work. Business outcomes come from objective measurement.
- objective_agent_runs: inspect this objective's Delegations (grantor, state, pause
  reason, control revision) each with its latest Job (wait state, exact saved review).
  Job completion never proves business results.
- objective_agent_context: reconstruct the objective agent's decision input:
  intent, timeframe, accepted approaches, exact work versions, dependency
  waits, missing context, and next decisions. Does not start a background
  agent or grant delegation. Verify results through objective_measurement;
  completed work does not release dependent approaches or prove success.
- objective_pilot_review: read expired-pilot evidence, owner, next check,
  and decision/preparation history (latest 20 entries; has_more marks the bound).
- objective_business: read business intent, contribution links and owned work;
  task and child completion never substitute for this objective's result.
- objective_setup_context: read the Architect inputs.
- objective_setup_list: read saved setup reviews, optionally filtered by
  payload {action_id}.
- objective_audience: read paginated accounts or people (payload =
  {view: "accounts"|"people", query?, status?, company_id?, unresolved?,
  limit?, offset?}). Counts and account outreach are projections.
- objective_audience_build: read the deterministic audience volume plan,
  required research facts, and latest saved sourcing run (no payload
  needed). The objective's calibration pilot (target.pilot) sizes a pilot
  plan; payload {pilot_size} is accepted only when it equals that pilot's
  max_contacts. Does not attach CRM people, invoke a model, or start
  providers. A pilot is not a meeting forecast. preparing_job reports the
  latest objective_source preparation: status pending|processing|
  completed|failed, phase crm_check|planning, checked of total CRM
  records with a verdict, and a readable error. Includes
  brief_context_fingerprint and research_brief_stale for reviewed briefs.
  fact_definitions lists workspace definitions with description,
  subject_type, and answer_schema. For an equivalent public question, copy
  these as fact_definition, subject_type and answer_schema in the reviewed
  brief. Leave fact_definition unset for private conversations and
  interpretations.
- objective_forecast: read the current derived path distribution, weekly
  channel load, target math, five sample plans, commitments, abstentions,
  and prior-forecast diff (no payload). blocking_reasons must be resolved
  before manage_outreach action=objective_launch.
  pilot_sequence_claim_required means the reviewed sequence and rationale
  are not yet saved through manage_outreach action=objective_pin.
- objective_touch_preview: draft one sequence step for one member of a
  draft or active objective, exactly as the in-app author would (payload =
  {person_id, step, channel?, prior_touches?}). Returns the draft, the
  verified research facts it was given and the ones it used, the notes a
  reviewer would see (no_verified_fact when research holds none), and the
  prose gate's payload. prior_touches are texts assumed sent for earlier
  steps, in step order: pass step 1's preview text to preview step 2
  against it. Writes no message, action or plan and sends nothing; each
  call runs the author model and records its cost in the ledger.
- objective_sourcing_plan: calculate the exact cohort size, live provider
  order, bounded cost and candidate limits, and blocking reasons. With a
  calibration pilot (target.pilot) the plan sources that pilot's
  max_contacts, existing eligible members first, without an observed
  conversion rate; set or change the pilot with objective_update. Without
  one, the plan needs observed conversion. Each call runs Vruum's sourcing planner model within
  the workspace's model budget; over budget, the plan returns without
  the planner's advice.
- objective_sourcing_run: read saved preparation counts and recovery
  (payload = {action_id}).
- objective_sourcing_recovery: read saved failure phase, resume
  eligibility, and current reviewed_inputs (payload = {job_id}).
  manage_outreach action=objective_sourcing_resume takes those
  reviewed_inputs.

## Headers

- `Idempotency-Key` string, nullable: Optional. Send a unique key (a UUID) so an exact retry of a SUCCESSFUL call replays the original response instead of re-running it — objective_sourcing_plan runs a budgeted planning model on every call. Same semantics as manage_outreach: a deterministic 4xx releases the key, an ambiguous failure pins it to a 409, a DIFFERENT body with the same key is a 409, and keys are scoped to your company for 24 hours.

## Request body

- WriterRequest: Uniform request body for every facade writer.
  - `action` string, required: The operation to perform — see the tool description for the action vocabulary and each action's id/payload semantics.
  - `id` union: Target entity id, or an ARRAY of ids to apply the same action+payload to each (max 100; see the tool description for which entity the id names per action).
    - string
    - string[]
  - `payload` object, nullable: Action-specific fields, validated by the underlying route's own schema (a bad field 422s with that route's precise errors). See the tool description per action.
  - `items` object[], nullable: For create-like actions only: an array of per-item payloads processed in order with per-item results (max 100). Mutually exclusive with `id` and `payload`.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/vruum/apis/vruum-public-api.md) · [All operations](https://skmtc.dev/vruum/apis/vruum-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vruum/apis/vruum-public-api/revisions/b8ada111c30a?raw)