# Simulation API

## Run a template

<mark style="color:green;">`POST`</mark> `https://nsim.iotify.io/api/test/:testID/run`

This endpoint allows you to run a test with the required run settings.

#### Path Parameters

| Name                                     | Type | Description                          |
| ---------------------------------------- | ---- | ------------------------------------ |
| testID<mark style="color:red;">\*</mark> |      | The ID of the test that needs to run |

#### Headers

| Name                                           | Type | Description                                |
| ---------------------------------------------- | ---- | ------------------------------------------ |
| Content-Type<mark style="color:red;">\*</mark> |      | application/json                           |
| key<mark style="color:red;">\*</mark>          |      | API token for the account                  |
| domain<mark style="color:red;">\*</mark>       |      | The domain under which your account exists |

#### Request Body

| Name                                            | Type    | Description                                                 |
| ----------------------------------------------- | ------- | ----------------------------------------------------------- |
| runSettings<mark style="color:red;">\*</mark>   | Object  | Defines the parameters for the simulation                   |
| jobName<mark style="color:red;">\*</mark>       |         | Unique name identifying the currently running job           |
| rS: clients<mark style="color:red;">\*</mark>   | Number  | Total number of clients                                     |
| rS: iteration<mark style="color:red;">\*</mark> | Number  | Total number of iterations                                  |
| rs: interval<mark style="color:red;">\*</mark>  | Number  | Interval between two iterations                             |
| rS: captureLogs                                 | Boolean | Capture all the log data to display on the results page     |
| rS: captureState                                | Boolean | Capture all the state data to display on the results page   |
| rS: capturePayload                              | Boolean | Capture all the payload data to display on the results page |

{% tabs %}
{% tab title="201: Created Test simulation successfully run" %}

```json
{
    "success": true,
    "jobId": "$jobID",
    "jobName": "$jobName"
}
```

{% endtab %}

{% tab title="400: Bad Request Failed to launch the test simulation " %}

```json
{
    "statusCode": 400,
    "message": "Error message",
    "error": "Error reason"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The parameters marked as `rS: $parameter` are parameters under the runSettings object.

For a list of all additional runSettings parameter you can use, check the Run Settings page of the documentation.
{% endhint %}

{% code overflow="wrap" %}

```javascript
// Example curl command

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "key:$KEY" -H "domain:nsim.iotify.io" -d '{"jobName":"$JOBNAME","runSettings":{"interval":1000,"iteration":150,"clients":10}}' nsim.iotify.io/api/test/$TESTID/run
```

{% endcode %}

## Get Job Status

<mark style="color:blue;">`GET`</mark> `https://nsim.iotify.io/api/jobs/:workspaceID/:jobID`

This API returns the status and results of the simulation job&#x20;

#### Query Parameters

| Name                                          | Type | Description                                                                                             |
| --------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
| workspaceID<mark style="color:red;">\*</mark> |      | WorkspaceID for the workspace you're a part of                                                          |
| jobID<mark style="color:red;">\*</mark>       |      | Simulation ID as seen in the UI or returned by API while launching the simulation through the POST API. |

#### Headers

| Name                                           | Type   | Description                                |
| ---------------------------------------------- | ------ | ------------------------------------------ |
| Accept<mark style="color:red;">\*</mark>       |        | application/json                           |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json                           |
| key<mark style="color:red;">\*</mark>          | String | API token for the account                  |
| domain<mark style="color:red;">\*</mark>       | String | The domain under which your account exists |

{% tabs %}
{% tab title="200 Simulation status and results" %}

```json
{
    "jobId": "$jobID",
    "testId": "$testID",
    "jobName": "$jobName",
    "workspaceId": "$workspaceID",
    "submitterId": "$submitterID",
    "runSettings": {
        "name": "Default",
        "interval": 1000,
        "iteration": 150,
        "clients": 10,
        "totalClients": 5,
        "clientIdOffset": 0
    },
    "currentInstance": 0,
    "results": {
        "result": {
            "total": 750,
            "success": 750,
            "failure": 0,
            "startAt": 1667282175065.829,
            "endAt": 1667282327070.1438,
            "duration": 152004.31469726562,
            "status": "finished",
            "eta": 0
        },
        "instances": {
            "0": {
                "result": {
                    "total": 750,
                    "success": 750,
                    "failure": 0,
                    "startAt": 1667282175065.829,
                    "endAt": 1667282327070.1438,
                    "duration": 152004.31469726562,
                    "status": "finished",
                    "eta": 0
                },
                "iterations": {
                    "0": {
                        "result": {
                            "total": 5,
                            "success": 5,
                            "failure": 0,
                            "startAt": 1667282175065.829,
                            "endAt": 1667282177692.3975,
                            "duration": 2626.568359375,
                            "status": "finished",
                            "eta": 0
                        }
                    },
                    
                    .............
                    
                    "149": {
                        "result": {
                            "total": 5,
                            "success": 5,
                            "failure": 0,
                            "startAt": 1667282327068.5632,
                            "endAt": 1667282327070.1438,
                            "duration": 1.58056640625,
                            "status": "finished",
                            "eta": 0
                        }
                    }
                }
            }
        }
    }
}
```

{% endtab %}

{% tab title="400 Simulation results not found" %}

```json
{
    "statusCode": 400,
    "message": "Error message"
}
```

{% endtab %}
{% endtabs %}

{% code overflow="wrap" %}

```javascript
// Example curl command

curl -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "key:$KEY" -H "domain:nsim.iotify.io" nsim.iotify.io/api/jobs/$WORKSPACE/$JOB
```

{% endcode %}


---

# 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.iotify.io/api/simulation.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.