AI Question Decomposer & Clarifying Questions

Break any hard or vague question into ranked sub-questions, the missing facts that block an answer, and a ready-to-send clarifying form with options.

Best for: question decomposition, clarifying questions, research planning.
Input and output: Agents and MCP clients can use the structured questions to choose the next evidence-gathering step.

What can Question Decomposer do?

Send one or more questions with any known context. The Actor returns the missing facts that block a good answer, the subquestions to work through, and a form that can collect the next answers.

What you get	Features
❓ Focused subquestions for each input question	📦 One dataset row per input item
📋 Ranked blockers and a ready clarification form	📝 JSON dataset plus Markdown report

Who this is for

• Prepare a question before research
• Find missing facts before a decision
• Build a clarification form for a user or client

What you get back

Field	Type	What you get	Example
index	integer	Position of this item in the input list.	1
status	string	Whether this item completed its requested analysis.	success
question	string	Question sent to the analysis service.	Should a 12-person SaaS team buy or build customer support automation?
subQuestions	array	Follow-up questions needed to answer the main question.	["What is the estimated development cost for customer support automation?","What is the average cost of a customer support automation tool for a SaaS team?",...
blockingBlanks	array	Ranked missing facts that block a reliable answer.	[{"rank":1,"question":"What is the estimated development cost for customer support automation?","whyItMatters":"If the cost is too high, building may not be...
clarifyingForm	array	Questions and options ready to show a user.	[{"id":"f1","question":"What is the estimated development cost for customer support automation?","options":[],"allowOther":true,"whyItMatters":"If the cost i...
error	null	Problem details when this item does not complete.	null
processedAt	string	Time the Actor processed this item.	2026-09-11T17:07:17.165222+00:00

The run also links to its dataset and any files named in the Actor output.

What you need to provide

Field	Type	Required	What it does	Example
items	array	Yes	Process one or more items in a single run. Each item produces exactly one dataset row.	[{"question":"Should our 12-person SaaS company build or buy customer support automatio...
items[].question	string	Yes	The vague, complex, or consequential question to decompose.	Should our 12-person SaaS company build or buy customer support automation?
items[].context	string	No	Optional known facts, constraints, audience, or desired outcome.	We need a recommendation for next quarter. Budget and timeline are not yet fixed.

Quick start

1. Open the Actor in Apify Console.
2. Click Try for free or Create a task.
3. Replace the sample values with your own input.
4. Click Start.
5. Open the dataset and the named output files when the run ends.

Pricing

• question-decomposed: $0.03 per question decomposed.
• Example: the 1-question sample costs $0.03; 100 questions cost $3.00 (up to 100 per run).
• You pay only for successful results. Failed or skipped items are not charged.
• Normal Apify compute and proxy costs may also apply.

Limits and honest notes

• The Actor does not answer the original question. It identifies what must be resolved first.
• Each item must contain a question. Context is optional.
• An item failure is saved as an error row. Other items can still finish.

Code and API

The examples below use the same values as the Apify Console sample.

Input JSON

{
  "items": [
    {
      "question": "Should our 12-person SaaS company build or buy customer support automation?",
      "context": "We need a recommendation for next quarter. Budget and timeline are not yet fixed."
    }
  ]
}

Real output sample

This excerpt comes from the real run named in the current marketplace release report.

{
  "index": 1,
  "status": "success",
  "question": "Should our 12-person SaaS company build or buy customer support automation?",
  "subQuestions": [
    "How likely is it that underestimating development effort will delay or derail the project?",
    "How concerned are you about vendor lock-in if you buy support automation?",
    "How likely is it that a custom-built solution will fail to meet support needs?"
  ],
  "blockingBlanks": [
    {
      "rank": 1,
      "question": "How likely is it that underestimating development effort will delay or derail the project?",
      "whyItMatters": "High risk of underestimation may make building less viable compared to buying a ready solution.",
      "category": "consequential"
    },
    {
      "rank": 2,
      "question": "How concerned are you about vendor lock-in if you buy support automation?",
      "whyItMatters": "High concern for vendor lock-in may favor building a custom solution.",
      "category": "sensitive"
    },
    {
      "rank": 3,
      "question": "How likely is it that a custom-built solution will fail to meet support needs?",
      "whyItMatters": "High risk of failure suggests a pre-built solution may be more reliable.",
      "category": "consequential"
    }
  ],
  "clarifyingForm": [
    {
      "id": "f1",
      "question": "How likely is it that underestimating development effort will delay or derail the project?",
      "options": [
        "Very likely",
        "Somewhat likely",
        "Unlikely"
      ],
      "allowOther": true,
      "whyItMatters": "High risk of underestimation may make building less viable compared to buying a ready solution."
    }
  ],
  "processedAt": "2026-09-11T04:23:15.795909+00:00"
}

curl

curl -X POST "https://api.apify.com/v2/acts/physealabs~question-decomposer/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d @input.json

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("physealabs/question-decomposer").call(run_input={'items': [{'question': 'Should our 12-person SaaS company build or buy customer support automation?', 'context': 'We need a recommendation for next quarter. Budget and timeline are not yet fixed.'}]})
items = client.dataset(run["defaultDatasetId"]).list_items().items

Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('physealabs/question-decomposer').call({"items": [{"question": "Should our 12-person SaaS company build or buy customer support automation?", "context": "We need a recommendation for next quarter. Budget and timeline are not yet fixed."}]});
const { items } = await client.dataset(run.defaultDatasetId).listItems();

You can call this Actor from an agent or LLM tool that can send HTTP requests to the Apify API. Keep the Apify token in a secret store.

FAQ

Does it answer my question?

No. It breaks the question into gaps and focused follow up questions.

Can one run contain several questions?

Yes. Add more objects to items.

What files does it save?

It saves dataset rows, RESULTS.md, and RUN_SUMMARY.json.