# Schedule Run Status API

The cURL commands listed in this article are components of scheduled APIs.

#### Schedule cURL

The schedule cURL is used to trigger tests in Sofy. The following parameters are required to trigger the schedule in Sofy.

- **SUBSCRIPTION_API_KEY**: To retrieve your subscription key, navigate to **Account > Account Settings > API Key**.
- **SCHEDULED_ID**: To retrieve your SCHEDULED_ID, navigate to **Automation > Runs & Results** and click on the **CI/CD Settings** integration icon next to the schedule name to capture the schedule ID.

```swift
curl --location "https://public.sofy.ai/scheduler-microservice/scheduled-runs/:scheduledRunGuid/status/:testRunGroupId" `
--header "x-sofy-auth-key: XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"  
--data-raw "{
    \"APIKey\":\"SUBSCRIPTION_API_KEY\",
    \"ScheduledID\": SCHEDULED_ID
    }"
```

Replace the placeholder authentication key, API key, and Scheduled ID values with the actual values.

##### Sample Response

ScheduleTestRunsGroupID is the ID returned in response. It can be used to retrieve the status of the scheduled runs. The above API will always trigger the schedule with the latest available build.

```bash
{
    "Message": "Test runs are scheduled and in queue, Login to https://portal.sofy.ai for more info.",
    "ScheduleTestRunsGroupID": *******
}
```

#### Triggering a Scheduled Build with a Specific Application Version

##### Triggering a Scheduled Build

Using the App Hash copied from the steps in [Capturing an Application Hash](https://docs.sofy.ai/using-ap-is-for-testing/schedule-run-status-api#Capturing-an-Application-Hash), use the following cURL command to trigger a scheduled build:

```swift
curl --location --request POST "https://api.sofy.ai/api/CICD/ScheduleAutomatedTestRun" \
--header "Content-Type: application/json" \
--data-raw "{
    \"APIKey\":\"SUBSCRIPTION_API_KEY\",
    \"ScheduledID\": SCHEDULED_ID,
    \"AppHash\":\"APP_HASH_FROM_BUILD_UPLOAD\"
    }"
```

You can use the App Hash copied from the steps under [Capturing an Application Hash](https://docs.sofy.ai/using-ap-is-for-testing/schedule-run-status-api#Capturing-an-Application-Hash) below.

##### Capturing an Application Hash

1. Log in to your Sofy account.
2. Select **App Manager** from the left navigation bar. 
3. Choose an app from the left panel.
4. Select the **Builds** tab.
5. Click the down-arrow icon to the left of the desired build name.
6. Select the **Copy Build ID** two pages icon next to the build to copy the App Hash. 
7. Enter the copied App Hash Build ID in the \"AppHash\" parameter in the Scheduled Build API.

#### Scheduling Status API

Status cURL uses `ScheduleTestRunsGroupID` to fetch the status of the scheduled run.

```swift
curl --location --request POST "https://api.sofy.ai/api/CICD/ScheduleAutomatedTestRunStatus?ScheduleTestRunsGroupID=SCHEDULED_TESTRUN_GROUP_ID" \
--header "Content-Type: application/json" \
--data-raw "{
   \"APIKey\":\"SUBSCRIPTION_API_KEY\",
   \"ScheduledID\":SCHEDULED_ID
   }"
```

##### Sample Response

```bash
[{\
    "ScheduleTestRunsGroupID": ******,\
    "ScheduleTestRunsGroupStatus": "Running"\
}]
```

Different ScheduleTestRunsGroupStatuses possibly returned by the API are:

- **Queued**: The schedule has been submitted to the scheduler and is awaiting device acquisition.
- **Running**: The device was acquired and test execution has kicked off.
- **Complete**: Test execution completed successfully. Test case results may be _Pass_ or _Fail_.
- **Complete with errors**: Test execution is completed but with statuses other than _Pass_ or _Fail_ for individual test runs. This includes—but is not limited to— _Not Executed_ or _Incomplete_.

#### Fetching the Schedule Test Run Group ID API

Status cURL uses `fetchTestRunGroupIDs` to fetch the scheduled test run group ID. A schedule test run group ID is generated each time a schedule is executed.

```swift
curl --location --request POST "https://api.sofy.ai/api/CICD/fetchTestRunGroupIDs" \
--header "Content-Type: application/json" \
--data-raw "{
   \"APIKey\":\"SUBSCRIPTION_API_KEY\",
   \"ScheduledID\":SCHEDULED_ID
   }"
```

##### Sample Response

```json
[{\
   "TestRunGroupID": "XXXXXX",\
   "ExecutedAt": "YYYY-MM-DDTHH:MM:SS.XXXZ",\
   "ScheduledRunSvgStatus": "Complete"\
},\
{\
   "TestRunGroupID": "XXXXXX",\
   "ExecutedAt": "YYYY-MM-DDTHH:MM:SS.XXXZ"\
   "ScheduledRunSvgStatus": "Complete With Errors"\
},\
{\
    "TestRunGroupID": "XXXXXX",\
    "ExecutedAt": "YYYY-MM-DDTHH:MM:SS.XXXZ"\
    "ScheduledRunSvgStatus": "In Queue"\
}]
```

#### Status of Individual Test Runs of the Schedule

```swift
curl --location --request POST 'https://api.sofy.ai/api/CICD/ScheduleAutomatedTestRunStatus'     --header 'Content-Type: application/json'  
--data-raw '{
\"APIKey\":\"SUBSCRIPTION_API_KEY\",
\"ScheduledID\":SCHEDULED_ID,
\"ScheduleTestRunsGroupID\":SCHEDULE_TEST_RUNS_GROUP_ID
}'
```

**Note**: ScheduleTestRunsGroupID is an optional parameter. If this parameter is not passed, the latest Schedule Test Run Group ID's results will be returned.

##### Response

```json
[{\
    "Scheduled_Name": "****",\
    "ScenarioName": "******",\
    "ScheduledAt": "2022-10-07T20:39:26.02",\
    "Version": "*****",\
    "CodeName": "",\
    "BuildNumber": "****",\
    "Manufacturer": "Apple",\
    "Model": "iPhone13,2",\
    "Statusvalue": "Passed"\
}]
```

##### Understanding the Test Run Status

- **Not Executed**: When a test case is executed, this status can be returned due to reasons like an internal server error.
- **Incomplete**: This test status is returned when the device is unavailable or the connection is lost or has failed.
- **Passed**: This status is returned when the test result has passed.
- **Failed**: This status is returned when the test result has failed.
- **Stopped**: This status is returned when the user force-stops the test.
- **Running**: This status is returned when execution is in progress.