Client Methods

Human Questions (Pending Tool Calls)

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.

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_calls`

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

Python

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

Terminal

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/pending_tool_calls?status=pending&limit=50" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Prop	Type	Default	Description
`status?`	`str`	`—`	Filter by status: pending, resolved, expired, superseded, or cancelled. If None, all statuses are returned.
`limit?`	`int`	`100`	Maximum number of results (1-500).

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

`get_pending_tool_call`

Fetch a single pending tool call by id.

Python

question = client.get_pending_tool_call("ptc_abc123")

Terminal

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/pending_tool_calls/ptc_abc123" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Prop	Type	Default	Description
`pending_tool_call_id`	`str`	`—`	The id of the pending tool call.

Returns a PendingToolCallResponse.

`resolve_pending_tool_call`

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.

Python

# 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}
)

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/pending_tool_calls/ptc_abc123/resolve" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "result": {
    "answer": "AWS ECS"
  }
}
JSON

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/pending_tool_calls/ptc_abc123/resolve" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "result": {
    "answer": "AWS ECS",
    "confidence": 0.9
  }
}
JSON

Prop	Type	Default	Description
`pending_tool_call_id`	`str`	`—`	The id of the pending tool call.
`answer?`	`str`	`—`	Human answer text, wrapped as {"answer": answer}. Provide this OR result.
`result?`	`dict`	`—`	Raw tool result payload. Provide this OR answer.
`valid_for_seconds?`	`int`	`—`	How long the resolved answer stays valid for reuse. Must be greater than 0. Server default when omitted.

Raises ValueError if both or neither of answer and result are provided. Returns the updated PendingToolCallResponse.

`update_pending_tool_call_answer`

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

Python

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

Terminal

curl -X PATCH "${REFLEXIO_URL:-https://www.reflexio.ai}/api/pending_tool_calls/ptc_abc123/answer" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "answer": "Google Cloud Run"
}
JSON

Prop	Type	Default	Description
`pending_tool_call_id`	`str`	`—`	The id of the pending tool call.
`answer`	`str`	`—`	The new (non-empty) answer text.
`valid_for_seconds?`	`int`	`—`	How long the edited answer stays valid for reuse. Must be greater than 0. Server default when omitted.

Returns the updated PendingToolCallResponse.

`mark_pending_tool_call_not_applicable`

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

Python

result = client.mark_pending_tool_call_not_applicable("ptc_abc123")

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/pending_tool_calls/ptc_abc123/not_applicable" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

Prop	Type	Default	Description
`pending_tool_call_id`	`str`	`—`	The id of the pending tool call.
`valid_for_seconds?`	`int`	`—`	How long the result stays valid for reuse. Must be greater than 0. Server default when omitted.

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

`cancel_pending_tool_call`

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

Python

cancelled = client.cancel_pending_tool_call("ptc_abc123")

Terminal

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/pending_tool_calls/ptc_abc123/cancel" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Prop	Type	Default	Description
`pending_tool_call_id`	`str`	`—`	The id of the pending tool call.

Returns the cancelled PendingToolCallResponse.

`PendingToolCallListResponse` Schema

Prop	Type	Default	Description
`pending_tool_calls?`	`list[PendingToolCallResponse]`	`—`	Matching pending tool calls, ordered newest first by the server.

`PendingToolCallResponse` Schema

Prop	Type	Default	Description
`id?`	`str`	`—`	Unique id of the pending tool call.
`org_id?`	`str`	`—`	Organization that owns the question.
`scope?`	`dict`	`—`	Scope dictionary the question was created under.
`scope_hash?`	`str`	`—`	Stable hash of the scope used for deduplication and prior-answer lookup.
`tool_name?`	`str`	`—`	Tool that requested human input (e.g. "ask_human").
`dedup_key?`	`str`	`—`	Tool-specific key used to deduplicate equivalent pending calls.
`status?`	`str`	`—`	pending, resolved, expired, superseded, or cancelled.
`question_text?`	`str`	`—`	The question posed to the human.
`user_id?`	`str \| None`	`—`	The user the question is scoped to, if any.
`args?`	`dict`	`—`	Arguments the tool was invoked with.
`tags?`	`list[str]`	`—`	Optional tags attached to the question.
`answer_format?`	`str \| None`	`—`	Hint describing the expected answer format, if any.
`result?`	`dict \| None`	`—`	The resolved result (e.g. {"answer": "AWS ECS"}). None until resolved.
`superseded_by?`	`str \| None`	`—`	Id of the question that superseded this one, if any.
`created_at?`	`datetime \| None`	`—`	When the question was created.
`resolved_at?`	`datetime \| None`	`—`	When the question was resolved.
`expires_at?`	`datetime \| None`	`—`	When the pending question expires.
`cache_until?`	`datetime \| None`	`—`	How long this pending call remains eligible for short-window deduplication.
`valid_until?`	`datetime \| None`	`—`	How long the resolved answer remains valid for reuse.