---
title: "Read an authorized Buzz human-adoption offer"
method: GET
path: "/buzz-human-adoption-offers/v1/{buzz_human_adoption_offer_id}"
tags: ["Buzz Control Plane"]
---

# Read an authorized Buzz human-adoption offer

`GET /buzz-human-adoption-offers/v1/{buzz_human_adoption_offer_id}`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/buzz-human-adoption-offers/v1/{buzz_human_adoption_offer_id}`
- Auth: one of:
  - API key in header `SIGN-IN-WITH-X`
  - HTTP bearer

Authorized only to the exact initiating agent SIWX authenticator or the target human/session lineage after an attempt exists. Unknown and unauthorized ids share the same 403 response.

## Path parameters

- `buzz_human_adoption_offer_id` string, required

## Response `200`

Authoritative converged offer state

- BuzzHumanAdoptionOffer
  - `buzz_human_adoption_offer_id` string, required
  - `org_id` string, uuid, required: A Run402 organization id, exactly as returned by GET /agent/v1/whoami, GET /orgs/v1 and GET /projects/v1. Buzz owns no organizations of its own.
  - `initiating_agent_principal_id` string, required
  - `identity_link_id` string, required
  - `expected_buzz_owner` object, required
    - `nostr_subject` string, required
    - `evidence` 'nip_oa_owner_attestation', required
    - `authoritative_for_run402` false, required
  - `status` 'available' | 'completed' | 'cancelled' | 'ineligible', required
  - `offer_url` string, uri, nullable, required
  - `deployment_context` BuzzHumanAdoptionDeploymentContext, required: Optional proof that the offer describes a real, currently-live deployment. All five fields are required together; no others are accepted. The gateway verifies project_id + release_id against the org's active release and live_url against its added subdomain, custom domain, or deployment host.
    - `project_id` string, required
    - `release_id` string, required
    - `live_url` string, uri, required
    - `source_revision` string, required
    - `verified_at` string, date-time, required
  - `current_buzz_human_adoption_id` string, nullable, required
  - `completed_buzz_human_adoption` object, nullable, required
  - `latest_attempt_receipt` BuzzHumanAdoptionAttemptReceipt, nullable, required
    - `attempt_reference` string, required
    - `status` 'pending' | 'active' | 'expired' | 'cancelled', required
    - `issued_at` string, date-time, nullable, required
    - `expires_at` string, date-time, nullable, required
    - `expired_at` string, date-time, nullable, required
    - `cancelled_at` string, date-time, nullable, required
    - `activated_at` string, date-time, nullable, required
    - `diagnosis_code` 'COMPLETED' | 'COMPLETION_REJECTED' | 'CLIENT_OBSERVED_COMPLETION_ERROR' | 'ATTEMPT_CANCELLED' | 'EXPIRED_AFTER_PROOF_RECEIVED' | 'EXPIRED_AFTER_INVALID_CALLBACK' | 'EXPIRED_AFTER_INVALID_MANUAL_PROOF' | 'EXPIRED_AFTER_CLIENT_COMPLETION_ERROR' | 'EXPIRED_AFTER_BUZZ_OPEN_REQUESTED' | 'EXPIRED_WITHOUT_BUZZ_OPEN_OBSERVED' | 'PROOF_RECEIVED_COMPLETION_PENDING' | 'INVALID_CALLBACK_RETRY_AVAILABLE' | 'INVALID_MANUAL_PROOF_RETRY_AVAILABLE' | 'BUZZ_OPEN_REQUESTED_CALLBACK_PENDING' | 'AWAITING_BUZZ_OPEN', required
    - `last_observed_stage` string, nullable, required
    - `last_trace_id` string, nullable, required
    - `milestones` BuzzHumanAdoptionAttemptReceiptMilestone[], required
      - `stage` 'attempt_created' | 'buzz_open_requested' | 'callback_received' | 'callback_invalid_observed' | 'manual_proof_submitted' | 'manual_proof_invalid_observed' | 'completion_error_observed' | 'completion_rejected' | 'completion_succeeded' | 'attempt_expired', required
      - `observed_at` string, date-time, required
      - `trace_id` string
      - `result_code` string
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `completed_at` string, date-time, nullable, required
  - `cancelled_at` string, date-time, nullable, required
  - `ineligible_at` string, date-time, nullable, required
  - `ineligible_reason` 'agent_inactive' | 'agent_not_sole_owner' | 'human_owner_exists' | 'identity_link_inactive' | 'owner_attestation_missing' | 'active_adoption_exists' | 'direct_adoption_pending', nullable, required
  - `next_actions` BuzzNextAction[], required
    - `type` string, required
    - `method` 'GET' | 'POST' | 'PATCH' | 'DELETE'
    - `path` string
    - `field` string: Exact rejected request field or header when the repair is field-specific.
    - `auth` string, required
    - `why` string, required
    - `safe_to_auto_execute` boolean, required
    - `requires_approval` boolean, required
    - `destructive` boolean, required
    - `idempotent` boolean, required
    - `spend_impact` object, required
      - `currency` 'USD', required
      - `max_amount` '0', required

## Other responses

- `403`: Canonical Buzz control-plane error. Authorization is existence-obscuring; proof failures never consume a challenge or partially create authority.

---

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