Multi-step quests
A participant finishes several steps and is paid once. What your app sends, what AdQuest decides, and how to read progress.
On this page
The picture in one minute
A multi-step quest is one quest with a checklist. The participant ticks off the steps, and AdQuest pays one reward after the last required step is verified. Think of it as a boarding pass: each stamp is a step, and the reward is the flight.
| Idea | What it means for you |
|---|---|
| One reward | The quest pays once. A step never pays, so you never grant anything per step. |
| The server decides | Your app can say "start" or "click". It can never say "done". AdQuest marks a step verified. |
| Each participant has an execution | Their personal run of the quest. It records which steps are verified and which steps are still open. |
| Steps have a version | If the owner edits the steps, new participants get the new version. People already running keep the old one. |
Before you start
- Participant sessions working, so you have a participant token for each user. See the participant sessions guide.
- Multi-step quests are enabled for your environment. If they are not, the step routes answer MULTI_STEP_DISABLED (404, or 503 when attempt holds are off) and the quest is not served.
- The quest belongs to your own platform and is active. Multi-step quests are private quests only.
- Your client declares the multi_step capability. The AdQuest SDK does this for you. A raw HTTP client must send the X-AdQuest-Runtime header shown below, or the quest is hidden from it and start answers 404 QUEST_NOT_FOUND.
- Your Secret Key, if your server reports activities, and your Event signing secret if a step uses a URL callback. Both stay on your server.
Who proves each step?
Find the step in the left column. The other columns say who proves it and what you have to build.
| Step type | Participant does | Proven by | You build |
|---|---|---|---|
| condition | Reaches a target, such as 3 orders, 5000 spent or a verified account | Your server | Report the step’s activity |
| custom → url_callback | Does something your system can confirm | Your server | An HTTPS endpoint that answers verified: true |
| custom → manual_review | Submits proof | A reviewer | Nothing. Staff approve or reject. |
| streak | Returns on consecutive days | Your server | Report the step’s daily activity |
| video, banner, survey, visit | Watches, reads, answers or visits | AdQuest | Call start, click or send answers. AdQuest measures time on its own. |
| profile, referral | Saves a profile or invites a friend | AdQuest | As for a single quest: a fresh session with the profile, or a reported signup |
What happens to a participant
| Stage | What happens | Step status |
|---|---|---|
| 1. Start | AdQuest reserves a slot and the budget, and binds the steps version to the participant. | All steps pending |
| 2. Steps | Each step moves on its own as proof arrives. | pending → verified (instant proof), pending → in_review → verified (a reviewer decides), in_review → rejected → in_review (resubmit, limited attempts) |
| 3. Admission | Every required step is verified. AdQuest admits the execution. | steps_complete is true |
| 4. Settlement | The reward is paid once. | settlement_status: pending → success |
- A verified step stays verified. Sending proof for it again changes nothing and answers 200.
- Sequential quests unlock a step only after every required step before it is verified. Unordered quests unlock all steps at once.
- An optional step never blocks the reward.
- Approval does not need the participant to be online. If a reviewer approves late, AdQuest takes a new hold under the same capacity and budget rules, and retries every minute if the quest is paused or full. Nothing is paid without a hold.
Walkthrough: place 2 orders, then verify your profile
This example uses a sequential quest with two steps: a condition step called orders (2 different orders) and a profile step called profile. Follow the numbers.
The publisher registers the activity order_placed, carrying an item id, once per platform. The quest’s orders step counts it.
Start the quest and read the execution.
When your server sees an order, report it as an activity. You do not name the quest or the step.
Read the execution again to show progress. Repeat until the step says verified.
The profile step unlocks. Once it is verified, AdQuest settles the quest.
import { createAdQuestClient } from "@adquest/sdk";
const client = createAdQuestClient({ baseUrl, apiKey, participantToken, externalUserId });
await client.startQuest(23, { requiresTimer: false });
const execution = await client.getQuestExecution(23);
// execution.execution_id, execution.steps_version, execution.steps[].statuscurl "https://api.adquest.io/api/v1/platform/quests/23/execution?external_user_id=user_123" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: TOKEN_FOR_THIS_USER" \
-H 'X-AdQuest-Runtime: {"runtime_version":1,"capabilities":["multi_step"]}'await reportActivities([
{ id: "order_" + orderId, type: "order_placed", user: externalUserId, occurred_at: Math.floor(Date.now() / 1000), entity_id: orderId },
]);Each fact is answered accepted or duplicate. A duplicate does not count twice.
{
"quest_id": 23,
"execution_id": 812,
"steps_version": 2,
"ordering": "sequential",
"state": "reserved",
"expires_at": "2026-11-09T15:30:00+00:00",
"steps": [
{ "step_key": "orders", "format": "condition", "status": "pending", "available": true,
"progress": { "current": 1, "target": 2, "unit": "items", "satisfied": false } },
{ "step_key": "profile", "format": "profile", "status": "pending", "available": false }
],
"steps_complete": false,
"settlement_status": "none"
}Condition steps in detail
A condition step reads: metric of an activity, operator, target. For example, count of order_placed is at least 3. Your server reports the activity as usual; AdQuest counts the facts that arrive after the step unlocks.
| Metric | Counts | Each fact must carry |
|---|---|---|
| occurrence | Whether it happened once | Nothing extra |
| count | Number of facts | Nothing extra |
| count_distinct | Different entity_id values, so one order counts once even if reported twice | entity_id (the activity carries an item id) |
| sum | Total of amount_minor, in one currency | amount_minor as an integer in minor units, and currency (the activity carries an amount) |
| state | A state fact equal to the step’s state, such as verified, reached after the step unlocks | state, with occurred_at = when it was reached (a state activity) |
- Operators: gte, gt, eq, lte, lt. A state step always uses eq. There are no expressions and no AND/OR inside one step. Use two steps for two conditions.
- The activity must be registered before the step is published. An unregistered one is refused with EVENT_NOT_REGISTERED.
- Only activity after the participant starts counts. In a sequential quest, only after that step unlocks.
- Facts may arrive late and in any order, up to 7 days after they happened. A fact more than 60 seconds in the future is refused.
- Amounts are integers in minor units (cents). 5000 with currency USD is 50.00 USD.
A refund is its own activity, registered as reversing order_placed. Report it with reverses set to the id of the original fact.
await reportActivities([
{ id: "refund_" + orderId, type: "order_refunded", user: externalUserId, occurred_at: Math.floor(Date.now() / 1000), entity_id: orderId, reverses: "order_" + orderId },
]);- The original fact stops counting. This works even if the refund arrives before the original.
- Before the quest is admitted, a refund can move a verified step back to pending. After admission, a refund changes nothing and the reward is not taken back.
Reading the state
Poll the execution, or read one step. Use these fields to drive your screen.
| Field | Use it to |
|---|---|
| steps[].status | Show pending, in_review, verified or rejected. |
| steps[].available | Grey out locked steps in a sequential quest. |
| steps[].progress | Show "2 / 3 items" for a condition step. |
| steps[].elapsed_seconds | Resume a video or timer countdown after the widget reopens. The server measures it. |
| steps[].review | Explain a rejection and whether the participant may resubmit. |
| state and expires_at | Show how long the reservation is held. |
| steps_complete | True when every required step is verified. |
| settlement_status | none, pending or success. Credit your own app only on success. |
| unsettled_reason | Why a complete execution is not paid yet, such as a paused quest. AdQuest keeps retrying. |
SDK calls you will use
| Goal | SDK method |
|---|---|
| Start the quest | startQuest(questId) |
| Read all steps | getQuestExecution(questId) |
| Read one step | getQuestStep(questId, stepKey) |
| Start, click, answer or send proof for a step | submitQuestStepEvidence(questId, stepKey, input) |
| Finish the quest | A state read. It returns 409 MULTI_STEP_REQUIRED until the required steps are verified. It never verifies anything. |
Errors and what to do
| Code | Meaning | What to do |
|---|---|---|
| MULTI_STEP_DISABLED | Multi-step quests are off for the environment (404), or attempt holds are off (503) | Ask AdQuest to enable it |
| QUEST_NOT_FOUND | On start or complete: the client did not declare multi_step, or the quest is not available | Send the runtime header |
| NOT_STARTED | The participant has no execution | Start the quest first |
| STEP_NOT_FOUND | step_key is not in the participant's version | Read the execution and use its keys |
| STEP_OUT_OF_ORDER | An earlier required step is not verified yet | Show the step as locked until available is true |
| STEP_NOT_STARTED | A timed step was submitted before start | Send action start, wait, then submit |
| MULTI_STEP_REQUIRED | Complete was called too early | Keep showing the steps. Do not retry in a loop. |
| EVENT_NOT_REGISTERED | The step’s activity is not registered for the platform | Register it, then publish the step |
| STEP_CALLBACK_ONLY | You sent evidence to a streak step | Streak steps move only from the daily activity your server reports |
| TIMING_ADMIN_ONLY | An owner set answer, gap or attempt time on a type that does not allow it | Only custom and multi-step quests accept an owner attempt time (15 minutes to 30 days). Leave timing to AdQuest elsewhere |
| RESERVATION_EXPIRED, QUEST_PROCESSING, QUEST_ALREADY_COMPLETED | The hold ended, is settling or is already paid | Read the execution and show the real state |
| ATTEMPTS_EXHAUSTED | Start after the participant’s only attempt ended unpaid | Show the quest as finished. A multi-step quest allows one attempt unless AdQuest changes the limit |
Step links, attempt time and checking your integration
A step can carry a link to your app (https or an app scheme such as myapp://orders). The SDK only opens it; your app still has to prove the step. Read it as config.action_url and config.action_label on the step.
Multi-step and custom quests can have an attempt time of 15 minutes to 30 days. Leave it empty for no deadline. After it passes, late evidence is refused and the attempt ends. A multi-step quest allows one attempt unless AdQuest raises the limit, so a new start then answers 409 ATTEMPTS_EXHAUSTED.
A url_callback check for a step also names step_key, execution_id and steps_version, signed the same way as for a custom quest. The publisher’s Activities page shows whether your server’s facts are arriving.
Mistakes people make
- Reporting activities from the browser. The Secret Key belongs on your server only.
- Reporting a fact before it is final, such as an unconfirmed deposit.
- Counting progress yourself. Read it from the execution.
- Treating complete as proof. It cannot verify a step.
- Forgetting the runtime header on raw HTTP. The quest then looks missing.
- Editing steps and expecting running participants to change. They keep their version; only new participants get the new steps.