# Tour History

Lists the free tours you gave with [Create Tour](https://my.nexusggr.com/app/docs/integration/freespin-tour-api/create-tour), newest first, with how far each has been played and what it has paid. Filter by user, by `tour_id`, or by when the tours were created.

A tour still being created is not listed, and neither is one the game server refused.

### Endpoint

```
POST https://api.nexusggr.com
```

**Content-Type:** `application/json`

### Request

**Method:** `tour_history`

```json
{
    "method": "tour_history",
    "agent_code": "your_agent_code",
    "agent_token": "your_agent_token",
    "user_code": "test",
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-10-15T23:59:59Z",
    "page": 0,
    "perPage": 100
}
```

| Field         | Type     | Required | Description                                                                  |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `method`      | string   | Yes      | Must be `tour_history`                                                       |
| `agent_code`  | string   | Yes      | Your agent code                                                              |
| `agent_token` | string   | Yes      | Your agent API token                                                         |
| `user_code`   | string   | No       | Only this user's tours                                                       |
| `tour_id`     | string   | No       | Only the tour with this `tour_id`                                            |
| `start`       | datetime | No       | Only tours created at or after this time, for example `2026-10-01T00:00:00Z` |
| `end`         | datetime | No       | Only tours created at or before this time                                    |
| `page`        | integer  | Yes      | Page number, from `0`                                                        |
| `perPage`     | integer  | Yes      | Tours per page, `1` – `1000`                                                 |

Give `start` and `end` in ISO 8601 with a time zone (`Z` for UTC). Leave out any filter you do not need. With none, every tour of your agent is listed.

### Response

#### Success

```json
{
    "status": 1,
    "code": 7777777,
    "msg": "SUCCESS",
    "total_count": 1,
    "page": 0,
    "perPage": 100,
    "tours": [
        {
            "tour_id": "free_tour_777",
            "user_code": "test",
            "provider_code": "PRAGMATIC",
            "game_code": "vs20doghouse",
            "bet_level": 1,
            "bet": 100,
            "total_bet": 2000,
            "spin_count": 10,
            "rest_count": 6,
            "amount": 70000,
            "real_win": 69960,
            "total_win": 15500,
            "status": "active",
            "expiration_time": "2026-10-16T06:46:04.000Z",
            "created_at": "2026-10-14T06:46:04.000Z",
            "updated_at": "2026-10-14T07:02:51.000Z"
        }
    ]
}
```

| Field             | Type    | Description                                                                          |
| ----------------- | ------- | ------------------------------------------------------------------------------------ |
| `total_count`     | integer | Tours that match the filters, on all pages                                           |
| `page`            | integer | The `page` you sent                                                                  |
| `perPage`         | integer | The `perPage` you sent                                                               |
| `tours`           | array   | The tours on this page, newest first                                                 |
| `tour_id`         | string  | The `tour_id` sent in `tour_create`                                                  |
| `user_code`       | string  | The user the tour was given to                                                       |
| `provider_code`   | string  | Game provider code                                                                   |
| `game_code`       | string  | The game the tour was given on                                                       |
| `bet_level`       | integer | The `bet_level` sent in `tour_create`                                                |
| `bet`             | number  | Coin bet of one line at `bet_level`                                                  |
| `total_bet`       | number  | Bet of one free round                                                                |
| `spin_count`      | integer | Free rounds in the tour                                                              |
| `rest_count`      | integer | Free rounds not played yet                                                           |
| `amount`          | number  | The `amount` sent in `tour_create`                                                   |
| `real_win`        | number  | What the tour's rounds were prepared to pay, and what your agent balance was charged. `null` if the tour failed before that was known |
| `total_win`       | number  | What the tour has paid the user so far                                               |
| `status`          | string  | Where the tour stands (table below)                                                  |
| `expiration_time` | string  | When the tour stops being playable (UTC)                                             |
| `created_at`      | string  | When the tour was created (UTC)                                                      |
| `updated_at`      | string  | When the tour last changed (UTC)                                                     |

| `status`     | Description                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `active`     | Can be played. `rest_count` rounds are left                                                    |
| `finished`   | All of its rounds were played. What they did not pay of `real_win` came back                   |
| `expiring`   | Its time ran out, and what it has not paid is being returned to your agent balance             |
| `expired`    | Its time ran out. What it had not paid came back                                               |
| `cancelling` | Being canceled with [Cancel Tour](https://my.nexusggr.com/app/docs/integration/freespin-tour-api/cancel-tour)         |
| `cancelled`  | Canceled. What it had not paid came back                                                       |
| `failed`     | Taken back right after it was created, for example because your agent balance did not cover `real_win`. What was charged came back |

#### Failure

```json
{
    "status": 0,
    "code": 7770400,
    "msg": "perPage must be less than or equal to 1000"
}
```

| Code      | Description                                                                         |
| --------- | ----------------------------------------------------------------------------------- |
| `7770400` | A field is invalid, for example `perPage` above `1000` or a `start` that is not a date. `msg` says which |
| `7770405` | `page` or `perPage` is missing                                                      |
| `7770500` | Internal error                                                                      |