Skip to documentation
AdQuestDocs

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.

IdeaWhat it means for you
One rewardThe quest pays once. A step never pays, so you never grant anything per step.
The server decidesYour app can say "start" or "click". It can never say "done". AdQuest marks a step verified.
Each participant has an executionTheir personal run of the quest. It records which steps are verified and which steps are still open.
Steps have a versionIf 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 typeParticipant doesProven byYou build
conditionReaches a target, such as 3 orders, 5000 spent or a verified accountYour serverReport the step’s activity
custom → url_callbackDoes something your system can confirmYour serverAn HTTPS endpoint that answers verified: true
custom → manual_reviewSubmits proofA reviewerNothing. Staff approve or reject.
streakReturns on consecutive daysYour serverReport the step’s daily activity
video, banner, survey, visitWatches, reads, answers or visitsAdQuestCall start, click or send answers. AdQuest measures time on its own.
profile, referralSaves a profile or invites a friendAdQuestAs for a single quest: a fresh session with the profile, or a reported signup

What happens to a participant

StageWhat happensStep status
1. StartAdQuest reserves a slot and the budget, and binds the steps version to the participant.All steps pending
2. StepsEach 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. AdmissionEvery required step is verified. AdQuest admits the execution.steps_complete is true
4. SettlementThe 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.

  1. The publisher registers the activity order_placed, carrying an item id, once per platform. The quest’s orders step counts it.

  2. Start the quest and read the execution.

  3. When your server sees an order, report it as an activity. You do not name the quest or the step.

  4. Read the execution again to show progress. Repeat until the step says verified.

  5. The profile step unlocks. Once it is verified, AdQuest settles the quest.

2. Start and read the execution (what the SDK client does)
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[].status
2. The same read over HTTP
curl "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"]}'
3. Your server reports one order — using reportActivities from Report activities
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.

4. What the execution looks like mid-way
{
  "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.

MetricCountsEach fact must carry
occurrenceWhether it happened onceNothing extra
countNumber of factsNothing extra
count_distinctDifferent entity_id values, so one order counts once even if reported twiceentity_id (the activity carries an item id)
sumTotal of amount_minor, in one currencyamount_minor as an integer in minor units, and currency (the activity carries an amount)
stateA state fact equal to the step’s state, such as verified, reached after the step unlocksstate, 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.

Report a refund — using reportActivities from Report activities
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.

FieldUse it to
steps[].statusShow pending, in_review, verified or rejected.
steps[].availableGrey out locked steps in a sequential quest.
steps[].progressShow "2 / 3 items" for a condition step.
steps[].elapsed_secondsResume a video or timer countdown after the widget reopens. The server measures it.
steps[].reviewExplain a rejection and whether the participant may resubmit.
state and expires_atShow how long the reservation is held.
steps_completeTrue when every required step is verified.
settlement_statusnone, pending or success. Credit your own app only on success.
unsettled_reasonWhy a complete execution is not paid yet, such as a paused quest. AdQuest keeps retrying.

SDK calls you will use

GoalSDK method
Start the queststartQuest(questId)
Read all stepsgetQuestExecution(questId)
Read one stepgetQuestStep(questId, stepKey)
Start, click, answer or send proof for a stepsubmitQuestStepEvidence(questId, stepKey, input)
Finish the questA state read. It returns 409 MULTI_STEP_REQUIRED until the required steps are verified. It never verifies anything.

Errors and what to do

CodeMeaningWhat to do
MULTI_STEP_DISABLEDMulti-step quests are off for the environment (404), or attempt holds are off (503)Ask AdQuest to enable it
QUEST_NOT_FOUNDOn start or complete: the client did not declare multi_step, or the quest is not availableSend the runtime header
NOT_STARTEDThe participant has no executionStart the quest first
STEP_NOT_FOUNDstep_key is not in the participant's versionRead the execution and use its keys
STEP_OUT_OF_ORDERAn earlier required step is not verified yetShow the step as locked until available is true
STEP_NOT_STARTEDA timed step was submitted before startSend action start, wait, then submit
MULTI_STEP_REQUIREDComplete was called too earlyKeep showing the steps. Do not retry in a loop.
EVENT_NOT_REGISTEREDThe step’s activity is not registered for the platformRegister it, then publish the step
STEP_CALLBACK_ONLYYou sent evidence to a streak stepStreak steps move only from the daily activity your server reports
TIMING_ADMIN_ONLYAn owner set answer, gap or attempt time on a type that does not allow itOnly 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_COMPLETEDThe hold ended, is settling or is already paidRead the execution and show the real state
ATTEMPTS_EXHAUSTEDStart after the participant’s only attempt ended unpaidShow the quest as finished. A multi-step quest allows one attempt unless AdQuest changes the limit

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.

Next steps

Something unclear, missing or wrong here? Tell us