# Submission flow

> A timed session: download each instance, solve it on your own machines, upload the solution in time.

Source: <https://frontieror-challenge.com/docs/self-hosted/submission-flow>

A Self-hosted submission is a timed session. You open it, download each private instance of the open round, solve it on your own machines by any means, and upload the solution before that instance's deadline. You can do this on the dashboard, with the [starter repository](https://frontieror-challenge.com/docs/self-hosted/example-code), or through the [API](https://frontieror-challenge.com/docs/self-hosted/api).

Each instance's clock starts when you download it. Its upload deadline is its time limit plus 60 seconds. An instance whose deadline would fall after the window closes cannot be started.

## Before you start

- Your team is on the Self-hosted track and a round is open. See [Rounds](https://frontieror-challenge.com/docs#rounds).
- Your team has a submission left today: one per UTC day, 4 during the testing stage. Opening a submission uses one, whether or not you upload anything.
- Your solver is ready. The instances are the open round's private Self-hosted instances, never published before. They have the same format as the public instances. The dashboard lists them with their time limits before you open a submission.

## 1. Open a submission

Opening a submission starts its window, which is long enough to solve every instance one after another: the sum of their time limits, plus 60 seconds of upload grace for each, plus 15 minutes. The window ends at the round's close at the latest. The dashboard shows the round's window before you open a submission, and so does [`GET /me`](https://frontieror-challenge.com/docs/self-hosted/api#get-your-account) in `round.self_hosted_window_s`.

Your team can have only one open submission at a time. The response lists every instance with its time limit.

## 2. Start each instance

Starting an instance downloads its file and starts its clock. Its upload deadline is its time limit plus 60 seconds of grace for the upload: two minutes after the download for an instance with a 60-second limit.

- Start the instances one at a time or all at once. Each has its own clock.
- An instance can be downloaded again until its deadline.
- An instance cannot be started if its deadline would fall after the window closes, so leave enough time for the last ones.

## 3. Upload one solution per instance

Upload the solution file before the instance's deadline. **Uploads are final**: the first one counts, and a second is refused.

At upload we check only that the file is a JSON object with a numeric `objective_value`. Feasibility and the objective are checked after the submission closes. See [Submission format](https://frontieror-challenge.com/docs/self-hosted/submission-format).

## 4. Close the submission

A submission closes when any of these happens:

- you upload the last instance's solution;
- you finish it: **Finish submission** on the dashboard, or [`POST …/finish`](https://frontieror-challenge.com/docs/self-hosted/api#finish-a-submission);
- its window runs out.

Instances without a solution then score 0 with “No solution submitted”. If nothing was uploaded at all, the submission is completed with a score of 0 straight away.

## 5. Evaluation

A closed submission is queued, then the checker verifies each solution and recomputes its objective. The status goes from Queued to Running to Completed, and the score and every instance's result appear on the dashboard and in [`GET /submissions/{id}`](https://frontieror-challenge.com/docs/self-hosted/api#get-a-submission). How the scores are computed is on [Evaluation and scoring](https://frontieror-challenge.com/docs/self-hosted/scoring).

## Dashboard, starter or API

| Step              | Dashboard               | API                                     |
| ----------------- | ----------------------- | --------------------------------------- |
| Open              | **Start submission**    | `POST /self-hosted/submissions`         |
| Start an instance | **Start and download**  | `POST …/instances/{instanceId}`         |
| Upload            | Choose the `.json` file | `PUT …/instances/{instanceId}/solution` |
| Finish            | **Finish submission**   | `POST …/{id}/finish`                    |

The starter's `uv run frontieror submit` does all four steps with the solvers in its `solvers/` folder.

## Statuses

| Status    | Meaning                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------- |
| Open      | The window is running.                                                                                  |
| Queued    | Closed and waiting for the checker.                                                                     |
| Running   | The solutions are being checked.                                                                        |
| Completed | Every instance has a result. The score counts on the leaderboard if it is the team's best in the round. |
| Failed    | The submission could not be evaluated. The reason is shown with it.                                     |