Skip to main content
await_review() is the no-document sibling of verify_document(). Reach for it when your agent needs a human judgment on text or structured data rather than a document: an approval, a classification, a free-text answer, a policy check, a “does this look right?” before the workflow continues. The reviewer sees your instruction plus any context you attach, fills a typed form, and the answer flows back into your code as a validated Pydantic instance. No file is uploaded, and it is billed as one standard page.
Requires awaithumans 0.1.11 or newer.

​
1. Install

pip install "awaithumans>=0.1.11"
No extras needed. await_review is pure SDK (httpx + pydantic); the document-processing extras are only for verify_document.

​
2. Get an API key

Sign in at app.awaithumans.dev, open API keys, and click Create key. Copy the ah_sk_live_... value once (you cannot see it again), then set it as an environment variable: 
export AWAITHUMANS_API_KEY="ah_sk_live_..."
New accounts start with a free trial credit. Pricing

​
3. Define the answer you want back

The reviewer fills a form generated from your Pydantic schema, so define exactly what your workflow needs: 
from pydantic import BaseModel, Field


class RefundDecision(BaseModel):
    approved: bool = Field(description="Approve the refund?")
    reason: str | None = Field(default=None, description="Why or why not")
A bool becomes a Yes/No switch, an Enum becomes a dropdown, a nested BaseModel becomes a section, and a list[BaseModel] becomes an editable table. Schema patterns

​
4. Call await_review

import asyncio
from awaithumans import await_review


async def main() -> None:
    decision = await await_review(
        task_description=(
            "Approve this $4,000 refund on order #4821? The item was "
            "returned and received back in the warehouse, and there are "
            "no prior refunds on the account. Reply yes or no with a "
            "short reason."
        ),
        response_schema=RefundDecision,
        task_metadata={
            "customer": "Acme Corp",
            "order": "#4821",
            "amount": "$4,000",
        },
    )

    if decision.approved:
        print("Approved:", decision.reason)
    else:
        print("Rejected:", decision.reason)


asyncio.run(main())
await_review() is async and long-polls the managed backend until the reviewer submits. For a synchronous workflow, use the sync wrapper: 
from awaithumans import await_review_sync

decision = await_review_sync(
    task_description="...",
    response_schema=RefundDecision,
)

​
Arguments

​
task_description
str
required
The instruction the reviewer reads. Markdown is supported, and long descriptions render as formatted prose.
​
response_schema
type[BaseModel]
required
The Pydantic model the reviewer’s answer is validated against before it returns to your code.
​
task_metadata
dict[str, str]
Free-form context shown to the reviewer verbatim, typically the data to judge ({"customer": "Acme", "amount": "$4,000"}). Keys and values are strings.
​
priority
"standard" | "high"
default:"standard"
"high" routes the task to the Express tier.
​
timeout_seconds
int
default:"172800"
Server-side task lifetime. Minimum 24h, maximum 30 days.

​
5. What the reviewer sees

The moment your call lands, the task appears in the reviewer dashboard (and notifies the review channel):
  1. Your task_description as the brief.
  2. A Context panel listing your task_metadata.
  3. A typed form built from response_schema (here, an approve switch and a reason box).
They fill it in and click Submit, and your await_review() call returns the typed RefundDecision with their answer.

​
6. Turnaround and pricing

  • Standard tier: typically a few hours.
  • Express tier (priority="high"): around 30 minutes during business hours.
  • Billed as one standard page ($0.80) per review, the same as a one-page document verification. Pricing

​
Hand this page to your coding agent

This page is self-contained. Point your coding agent (Claude Code, Cursor, and similar) at this URL and ask it to add an await_review step to your workflow. Everything it needs (install, key, schema, call, response handling) is above.

Verify a document instead

Same managed reviewers, for tasks where a document is the thing being checked.

Response schemas

Patterns for nested models, tables, optionals, and enums.

Pricing

Per-review cost, the Express tier, and how credit works.

Errors

Every exception, what triggers it, and the fix.