# Users' progress

This service returns the list of the users registered to the challenge, who were ranked and had enough data before the challenge started (*i.e.*, has made at least 10 trips during the pre-challenge period).

The service returns their progress (*i.e.* score comparison before and during the challenge) and all the ranking details (number of trips, distance, score). The list is sorted from best to worst progression.

If the challenge has not yet finished, the service will return a HTTP 204 (no body) response, along with a `Retry-After` header containing the date at which the response will be available:

```http
Retry-After: Wed, 21 Oct 2022 07:28:00 GMT
```

If the challenge only concerns a specific group (or groups), then the service also accepts a `group` request parameter to retrieve the progressions for a single group. If no value is provided, then the global progressions are returned.

{% hint style="info" %}
If you have your **admin API key**, you can try the API via this [**link**](https://drivequant.stoplight.io/docs/drivequant-public/5393cf05159ec-list-all-users-progress).
{% endhint %}

{% openapi src="/files/osFwnNfAb4AWP4NEZNUc" path="/drivekit/admin/challenges/{challengeId}/progress" method="get" %}
[drivekit-admin-challenge-v3.yml](https://2525923625-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LXYIG5U3AO65YYFWJRK%2Fuploads%2FN7KAiaeCZUgSyP3ciH8Y%2Fdrivekit-admin-challenge-v3.yml?alt=media\&token=8308057e-25b8-4b42-8b57-aab662abd6b5)
{% endopenapi %}

***

## Response

The table below summarizes the elements included in the `ChallengeProgressResponse` object.

<table><thead><tr><th width="217.66666666666666">Field</th><th width="193">Type</th><th>Description</th></tr></thead><tbody><tr><td>challengeId</td><td><code>string</code></td><td>Unique identifier of the challenge</td></tr><tr><td>group</td><td><code>string</code></td><td>If present, indicates that the rankings are specific for this group label</td></tr><tr><td>registeredUsers</td><td><code>int</code></td><td>Total number of users registered to the challenge</td></tr><tr><td>rankedUsers</td><td><code>int</code></td><td>Total number of users ranked in the challenge</td></tr><tr><td>usersWithDataBefore</td><td><code>int</code></td><td>Total number of users who have enough data before the challenge started</td></tr><tr><td>totalDistance</td><td><code>int</code></td><td>Total distance driven by the users for the challenge</td></tr><tr><td>totalNumberTrips</td><td><code>int</code></td><td>Total number of trips made by the users for the challenge</td></tr><tr><td>users</td><td><code>array[object]</code></td><td>List of users ranked in the challenge with enough data before the challenge <em>(see</em> <a href="#usernotranked"><em>UserNotRanked</em></a><em>)</em></td></tr></tbody></table>

### UserRankedWithProgress

The table below summarizes the elements included in the `UserRankedWithProgress` object.

<table><thead><tr><th width="217.66666666666666">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>username</td><td><code>string</code></td><td>Unique identifier of the user</td></tr><tr><td>firstname</td><td><code>string</code></td><td>First name of the user</td></tr><tr><td>lastname</td><td><code>string</code></td><td>Last name of the user</td></tr><tr><td>registerDate</td><td><code>string</code></td><td>Date at which the user entered the challenge<br><em>Date format: <code>YYYY-MM-dd’T’HH:mm:ss.SSSZ</code></em></td></tr><tr><td>numberTrips</td><td><code>int</code></td><td>Number of trips since the user registered to the challenge</td></tr><tr><td>distance</td><td><code>int</code></td><td>Distance since the user registered to the challenge</td></tr><tr><td>rank</td><td><code>int</code></td><td>Current rank of the user</td></tr><tr><td>score</td><td><code>double</code></td><td>Score of the user during the challenge</td></tr><tr><td>scoreBefore</td><td><code>double</code></td><td>Score of the user during the pre-challenge period</td></tr><tr><td>scoreEvolution</td><td><code>double</code></td><td>Evolution of the score of the user (<em>i.e.</em>, effect of the challenge on the user's score)</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.drivequant.com/backend/challenges/users-progress.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.