API Reference

Human Questions

Methods for listing and answering the resumable agent's pending tool calls (ask_human questions).

The resumable extraction agent can pause mid-extraction and ask a human a question when it needs information it cannot infer on its own. Each question is stored as a pending tool call (with tool_name == "ask_human"). Answering it unblocks the agent: dependent extraction runs are scheduled to resume with the supplied answer.

These methods cover the same endpoints the web portal's /questions page uses.

Storage requirement

Pending tool calls require a storage backend that supports durable agent-run state, such as SQLite, Supabase, or Postgres-compatible storage. Disk storage does not support this feature.

Method	Purpose
`list_pending_tool_calls`	List questions, optionally filtered by status
`get_pending_tool_call`	Fetch a single question by id
`resolve_pending_tool_call`	Answer a question and unblock the agent
`update_pending_tool_call_answer`	Edit a previously submitted answer
`mark_pending_tool_call_not_applicable`	Resolve a question as "no information"
`cancel_pending_tool_call`	Cancel a still-pending question without answering

A typical loop: poll list_pending_tool_calls(status="pending"), then call resolve_pending_tool_call(id, answer=...) for each one.

list_pending_tool_callsmethod

List pending tool calls for the organization, optionally filtered by status.

response = client.list_pending_tool_calls(status="pending", limit=50)for question in response.pending_tool_calls:    print(question.id, question.question_text)

Prop	Type
`status`	string
`limit`	integer

Returns a PendingToolCallListResponse whose pending_tool_calls is a list of PendingToolCallResponse (see schema below).

get_pending_tool_callmethod

Fetch a single pending tool call by id.

question = client.get_pending_tool_call("ptc_abc123")

Prop	Type
`pending_tool_call_id`required	string

Returns a PendingToolCallResponse.

resolve_pending_tool_callmethod

Answer a question, marking it resolved and scheduling dependent agent runs to resume. Provide exactly one of answer (the common ask_human case, wrapped as {"answer": ...}) or result (an arbitrary tool-result payload). The client raises ValueError before sending the request if both or neither are provided.

resolve-pending-tool-call.py

# Common case: answer an ask_human question.resolved = client.resolve_pending_tool_call("ptc_abc123", answer="AWS ECS") # Advanced: send a raw tool result payload.resolved = client.resolve_pending_tool_call(    "ptc_abc123", result={"answer": "AWS ECS", "confidence": 0.9})

Prop	Type
`pending_tool_call_id`required	string
`answer`	string
`result`	dict
`valid_for_seconds`	integer

Danger

Raises ValueError if both or neither of answer and result are provided.

Returns the updated PendingToolCallResponse.

update_pending_tool_call_answermethod

Edit the answer of an already-resolved ask_human question. Editing schedules another resume of dependent agent runs with the new answer.

edited = client.update_pending_tool_call_answer("ptc_abc123", "Google Cloud Run")

Prop	Type
`pending_tool_call_id`required	string
`answer`required	string
`valid_for_seconds`	integer

Returns the updated PendingToolCallResponse.

mark_pending_tool_call_not_applicablemethod

Resolve an ask_human question with the standard "user does not have information about this question" result, so dependent agent runs can proceed.

result = client.mark_pending_tool_call_not_applicable("ptc_abc123")

Prop	Type
`pending_tool_call_id`required	string
`valid_for_seconds`	integer

Returns the resolved PendingToolCallResponse (its result includes "not_applicable": true).

cancel_pending_tool_callmethod

Cancel a still-pending question without answering it. Only questions in the pending status can be cancelled.

cancelled = client.cancel_pending_tool_call("ptc_abc123")

Prop	Type
`pending_tool_call_id`required	string

Returns the cancelled PendingToolCallResponse.

PendingToolCallListResponseresponse model

Prop	Type
`pending_tool_calls`	list[PendingToolCallResponse]

PendingToolCallResponseresponse model

Prop	Type
`id`	string
`org_id`	string
`scope`	dict
`scope_hash`	string
`tool_name`	string
`dedup_key`	string
`status`	string
`question_text`	string
`user_id`	string \| None
`args`	dict
`tags`	list[string]
`answer_format`	string \| None
`result`	dict \| None
`superseded_by`	string \| None
`created_at`	datetime \| None
`resolved_at`	datetime \| None
`expires_at`	datetime \| None
`cache_until`	datetime \| None
`valid_until`	datetime \| None

PreviousOperations Next Client Configuration