# Quest methods

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

Source: https://dashboard.adquest.batriders.ir/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.

```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 | Set to false for quests with no timer, such as a survey. |
| 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);
await session.waitForDuration();
const question = await session.getQuestion();
const result = await session.complete(question.options[0].id);
```

## 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 | no | 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.

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

```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 }.

## ingestQuestEvent

### `ingestQuestEvent`

Sends an event for an event or custom quest. Sending the same eventId again returns duplicate: true.

```typescript
ingestQuestEvent(questId: number, payload: QuestEventPayload): Promise<{ eventId: string; duplicate: boolean }>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |
| payload.eventId | string | yes | Your unique ID for the event. |
| payload.eventName | string | yes | The event the quest is waiting for. |
| payload.timestamp | string | yes | When the event happened. |
| payload.signature | string | no | Signature for server-signed events. |
| payload.deliveryToken | string | no | Token from the quest start. |
| payload.source | string | no | Where the event came from. |

**Returns:** A Promise of { eventId, duplicate }.

## getGrowthStatus

### `getGrowthStatus`

Returns the user’s state on a profile, referral, streak or custom quest. 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.

## attributeReferral

### `attributeReferral`

Credits the inviter when a new user arrives with their referral code. Referral quests only.

```typescript
attributeReferral(questId: number, referralCode: string, deviceFingerprint?: string): Promise<Record<string, unknown>>
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| questId | number | yes | Quest ID. |
| referralCode | string | yes | The inviter’s code. |
| deviceFingerprint | string | no | An optional device fingerprint. |

**Returns:** A Promise of the attribution result.

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

> **Streak quests.** Streak days are not completed through the SDK. Your backend submits each day to the quest’s callback URL.

## Next steps

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