# Quest methods

> Client methods for listing quests, starting them and sending evidence.

Source: https://dashboard.adquest.io/docs/sdk/quests · Audience: Developers · Section: SDK reference

## getQuests

### `getQuests`

Lists the quests this platform can show. If a user is set, each quest’s completed flag is filled in.

```typescript
getQuests(): Promise<Quest[]>
```

**Returns:** A Promise of Quest[].

```typescript
const quests = await client.getQuests();
```

## getQuest

### `getQuest`

Loads one quest.

```typescript
getQuest(questId: number): Promise<Quest>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of Quest.

## startQuest

### `startQuest`

Starts a quest for the current user and returns a QuestSession that tracks the rest of the flow. Needs a user and a participant token. Starting again too soon throws RESTART_TOO_SOON; details.retry_after says how many seconds to wait.

```typescript
startQuest(questId: number, options?: StartQuestOptions): Promise<QuestSession>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |
| options.watchDuration | number | no | Seconds the participant must watch, for timed quests. |
| options.requiresTimer | boolean | no | Defaults to false. Set it to true for a video or banner quest, so getQuestion, getQuestions and complete throw TIMER_NOT_STARTED until the watch time has passed. Wait with waitForDuration() first. |
| options.mediaDriven | boolean | no | Set to true when real media playback drives the timer. |

**Returns:** A Promise of QuestSession.

```typescript
const session = await client.startQuest(23, { requiresTimer: true });
await session.waitForDuration();
const questions = await session.getQuestions();
// showQuestion is your own UI: it resolves with the option the participant chose.
let result;
if (session.supportsAnswers) {
  for (const question of questions) {
    const answered = await session.answer(question.id, await showQuestion(question));
    if (answered.done) { result = answered.result; break; }
    // A first miss on a graded question (answered.correct === false) is asked once more after the others.
  }
} else {
  result = await session.complete(await showQuestion(questions[0]));
}
```

## awaitCompletion

### `awaitCompletion`

Returns where the participant’s attempt at this quest stands, and polls while it is being settled. Needs a user and a participant token.

```typescript
awaitCompletion(questId: number, options?: { signal?: AbortSignal; untilSettled?: boolean }): Promise<QuestCompleteResult>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |
| options.signal | AbortSignal | no | Abort the polling, for example when the screen closes. |
| options.untilSettled | boolean | no | Keep polling until the attempt is settled. |

**Returns:** A Promise of QuestCompleteResult.

## getQuestExecution

### `getQuestExecution`

Reads the participant’s multi-step execution: the definition version it runs on, every step with its status, and the settlement status of the parent quest. Needs a participant token.

```typescript
getQuestExecution(questId: number): Promise<QuestExecution>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of QuestExecution.

```typescript
const execution = await client.getQuestExecution(23);
```

## getQuestStep

### `getQuestStep`

Reads one step of a multi-step execution, including its manual-review status. Needs a participant token.

```typescript
getQuestStep(questId: number, stepKey: string): Promise<QuestStepState>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |
| stepKey | string | yes | The step’s key. |

**Returns:** A Promise of QuestStepState.

```typescript
const step = await client.getQuestStep(23, "proof");
```

## submitQuestStepEvidence

### `submitQuestStepEvidence`

Asks the server to verify one step. The server decides; a completed flag is never sent. Use action start or click for timed and visit steps, evidence for manual review and answers for survey steps.

```typescript
submitQuestStepEvidence(questId: number, stepKey: string, input: StepEvidenceInput, attempt?: StepAttempt): Promise<QuestStepState>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |
| stepKey | string | yes | The step’s key. |
| input | StepEvidenceInput | yes | action, evidence, evidenceType or answers. |
| attempt | StepAttempt | no | The reservation id and delivery token of the current attempt. |

**Returns:** A Promise of QuestStepState; read status in_review for a step awaiting review.

```typescript
const step = await client.submitQuestStepEvidence(23, "proof", { evidence: "receipt-123" });
```

## getQuestReview

### `getQuestReview`

Reads where the participant’s manual review stands. Needs a participant token.

```typescript
getQuestReview(questId: number): Promise<Record<string, unknown>>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of the review record.

```typescript
const review = await client.getQuestReview(23);
```

## trackView

### `trackView`

Records that the user saw the quest. Needs a user and a participant token.

```typescript
trackView(questId: number): Promise<void>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise that resolves when the view is recorded.

## trackClick

### `trackClick`

Records a real click on the quest’s media. Needs a user and a participant token.

```typescript
trackClick(questId: number): Promise<void>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise that resolves when the click is recorded.

## visitQuest

### `visitQuest`

Attributes a visit for a visit quest and returns the destination. Needs a user and a participant token.

```typescript
visitQuest(questId: number): Promise<{ redirectUrl: string }>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of { redirectUrl }.

## getGrowthStatus

### `getGrowthStatus`

Returns the user’s state on an event, profile, referral, streak or custom quest: progress toward an event goal, the referral code, streak days or the custom review. Needs a user and a participant token.

```typescript
getGrowthStatus(questId: number): Promise<GrowthStatus>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of GrowthStatus.

### `getStreakStatus`

Returns the streak part of the growth status.

```typescript
getStreakStatus(questId: number): Promise<StreakStatus | null>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of StreakStatus, or null when the quest has none.

### `getCustomStatus`

Returns the custom-quest part of the growth status.

```typescript
getCustomStatus(questId: number): Promise<CustomStatus | null>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of CustomStatus, or null when the quest has none.

## getQuestStats

### `getQuestStats`

Returns engagement counts for the quest on your platform.

```typescript
getQuestStats(questId: number): Promise<QuestStats>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |

**Returns:** A Promise of { id, name, seenCount, clickedCount, answeredCount, engagementRate }.

> **Event, referral and streak quests.** These settle from the activities your server reports. There is no SDK call that completes them.

## Next steps

- [Quest session](https://dashboard.adquest.io/docs/sdk/quest-session): The object startQuest returns.
- [Reward methods](https://dashboard.adquest.io/docs/sdk/rewards): Balance, lotteries and claims.
- [Quest evidence](https://dashboard.adquest.io/docs/quest-evidence): The proof each format needs.
