> For the complete documentation index, see [llms.txt](https://algolytics-technologies.gitbook.io/algolytics/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://algolytics-technologies.gitbook.io/algolytics/scoring.one-platform/rest-api/scenario-execution-with-api.md). # Scenario execution with API Scenarios can be executed not only by * other [scenarios](/algolytics/scoring.one-platform/scenario-building-blocks/scenario-code.md) * in FORMS on the Scoring.one web portal (see section Forms in [Sidebar menu overview](/algolytics/scoring.one-platform/sidebar-menu-overview.md)) * using API by any other software. Here, we are going to focus on the last method. Using API is allows external services to execute scenario in a popular HTTP request format. There are three ways of executing scenarios via API: * **synchronous** - execute single scenario and wait for the result * **asynchronous** - execute single scenario, do something else, get the result when ready * **batch** - send multiple task for multiple scenarios as a single request and receive individual results ## Synchronous scenario execution Detailed documentation can be found here: [https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=handleRemoteScorePost
]() Example request: ```http POST https://api.algolytics.pl/scoringone/api/scenario/code/remote/score?name=testowy&key=65cd4409-b7f3-48b8-9675-d36c72d9f430 HTTP/1.1 Content-Type: application/json Cache-Control: no-cache { "a": "100" } ``` where `testowy` is the name of scenario and a key value `65cd4409-b7f3-48b8-9675-d36c72d9f430` is a dummy value for Scoring.One service token. A token can be found in [User Settings](/algolytics/scoring.one-platform/sidebar-menu-overview.md#user-settings) in the main menu. A payload of the POST request is in our example a single variable "a", which is equal to "100". The names and values of variables in a payload should match variable names expected by the scenario. Example requests in many formats (HTTP, C#, Curl, Java, JavaScript, PHP, Python, Ruby, Swift) can be found on the [documentation](https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=handleRemoteScorePost). Example response contains metadata related to the process of reqeust execution, e.g. content-type, date and result of the scenario.
## Asynchronous scenario execution Another option is to call scenario asynchronously. A POST request is send to specify what is to be computed and then GET request is used to retrieve the results. Example POST request: {% code overflow="wrap" %} ```http POST https://api.algolytics.pl/scoringone/api/scenario/code/scoreasync/testowy HTTP/1.1 Score-Token: xxxxxxxxxxxxxxxxxxxxxxxxx X-SCE-RequestId: id_12345 X-SCE-CallbackUrl: http://echo.jsontest.com X-SCE-CallbackRetryCount: 3 X-SCE-CallbackRetryDelay: 30 Content-Type: application/json Cache-Control: no-cache { "a": "123" } ``` {% endcode %} Example GET request: {% code overflow="wrap" %} ```http GET https://api.algolytics.pl/scoringone/api/scenario/code/scoreasyncresult/testowy HTTP/1.1 X-SCE-RequestId: id_12345 Cache-Control: no-cache Score-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` {% endcode %} More details in documentation for [POST](https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=handleScoreAsync\&definition=ApiScenarioCodeScoreasync-name-Post200-Response) and [GET](https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=handleScoreAsync_1) requests. ## Batch scenario execution This option is used to run a scenario multiple times with different input data. The procedure consists of three steps: 1. Send a batch of data; receive an identifier of a batch 2. Check if the data is processed; receive a list of identifiers of individual results 3. Get individual results Each step has a dedicated endpoint. An example of sending a two element batch is presented below. {% code overflow="wrap" %} ```http POST https://api.algolytics.pl/scoringone/api/batch/score?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1 Content-Type: application/json Cache-Control: no-cache { "scenarioName": "testowy", "parameters": [ {"a": "123"}, {"a": "456"} ] } ``` {% endcode %} *(More about this request:* [*https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=getTestsCases*](https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=getTestsCases)*)* The payload of this request requires two fields: * scenarioName - scenario name to be executed * parameters - a list of objects with input parameters for the scenario In response we should obtain batchTaskId which identifies our batch. It is then used to send another request, which checks whether the results are ready. {% code overflow="wrap" %} ```http GET https://api.algolytics.pl/scoringone/api/batch/65cd4409-b7f3-48b8-9675-d36c72d9f430?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1 Cache-Control: no-cache ``` {% endcode %} *(More about this request:* [*https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=getTestsCases\_1*](https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=getTestsCases_1)*)* Here, the value `65cd4409-b7f3-48b8-9675-d36c72d9f430` is an example value of batchTaskId. This time we should receive a list resultsIds containing identifiers of the results for every scenario in the batch, in the same order as in the batch. As long as all scenarios from the batch are not finished, the returned list resultsIds will be empty. If any scenario crashes during execution, it will not harm the whole batch, just the error message will be instead of the results. To download the results, for each id in the list we need to make the following request: {% code overflow="wrap" %} ```http GET https://api.algolytics.pl/scoringone/api/scenario/code/scoreasyncresult/testowy HTTP/1.1 X-SCE-RequestId: id Cache-Control: no-cache Score-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` {% endcode %} *(More about this request:* [*https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=handleScoreAsync\_1*](https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation\&operation=handleScoreAsync_1)*)* ### A trick to run multiple different scenarios The procedure described above requires that the batch consists of a list of the same scenarios, which differ in arguments only. What if we want to send different scenarios? We can create a wrapping scenario, which will run any other scenario inside. Let's name the scenario scenario\_wrapper which takes two input arguments: scenario\_name, scenario\_input. Then, a request sending a batch to server will look like this ```http POST https://api.algolytics.pl/scoringone/api/batch/score?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1 Content-Type: application/json Cache-Control: no-cache { "scenarioName": "scenario_wrapper", "parameters": [ {"scenario_name": "testowy", "scenario_input": {"a":"123"}}, {"scenario_name": "other_scenario", "scenario_input": {"name":"John", "age": "30"}} ] } ``` Although we can run multiple different scenarios in this way, it may not be optimal. If some scenarios require much more time than the others, we will wait for the results until the most time consuming scenario is finished.