Schedule Run Status API Endpoints - Sofy Support Docs: No-Code Automation Testing Platform Help

Schedule Run Status API Endpoints

Below, we’ve listed out the existing route, the new route, and the functionality for the changed routes.

The following parameters are required to trigger the schedule in Sofy:

Functionality

Fetch the status of a scheduled automated test run.

Schedule Run Status Route

curl --location "https://public.sofy.ai/scheduler-microservice/scheduled-runs/:scheduledRunGuid/status/:testRunGroupId" `
--header "x-sofy-auth-key: XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Replace the placeholder authentication key with the actual values

Response:

{
    "data": [
        {
            "scheduledRunName": "tomorrow",
            "testRunGroupId": "XXXXXX",
            "scenarioName": "alextest",
            "scheduledAt": "2023-10-24T06:14:39.200Z",
            "build": "1.43.0.release-candidate(5768)",
            "device": "iPad 7th Gen",
            "status": "Run Stopped"
        }
    ],
    "message": "Fetched 1 record(s)."
}

Error Response:

{
    "error": {
        "message": "Error message.",
        "details": "Error details.",
        "timestamp": "2023-10-23T09:23:51.845Z"
    }
}

Triggering a Scheduled Build with a Specific Application Version

Using the App Hash copied from the steps in Capturing an Application Hash, use the following cURL command to trigger a scheduled build:

curl --location --request POST "https://public.sofy.ai/scheduler-microservice/scheduled-runs/:scheduledRunGuid/execute?appHash=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" `
--header "x-sofy-auth-key: XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
--data-raw "{
    \"APIKey\":\"SUBSCRIPTION_API_KEY\",
    \"ScheduledID\": SCHEDULED_ID,
    \"AppHash\":\"APP_HASH_FROM_BUILD_UPLOAD\"
    }"

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

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.

Status of Individual Test Runs of the Schedule

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,
     \"ScheduleTestRunsGroupID\":SCHEDULE_TEST_RUNS_GROUP_ID
     }'

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

Replace the placeholder API key, Scheduled ID, and Schedule Test Runs Group ID values with the actual values.

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

Fetching All Scheduled Test Runs Results

This retrieves scheduled test runs within a specified date range. Results can be filtered by application (optionally) and retrieved in pages. If no date range is provided, the last 7 days are returned by default.

All requests must include your Sofy authentication key as a request header.
Header Type Required Description
x-sofy-auth-key string Required Your Sofy API authentication key.

Query parameters
All parameters are optional. Defaults are applied when parameters are omitted.
Parameter Type Required Description
fromDate string Optional Start of the date range in UTC. Format: YYYY-MM-DD HH:MM.Default: current date minus 7 days
endDate string Optional End of the date range in UTC. Format: YYYY-MM-DD HH:MM.Default: current date
pageNumber number Optional Page number for paginated results. Starts at 1.Default: 1
pageSize number Optional Number of records to return per page. Maximum value is 100 — any higher value is automatically capped.Default: 20 · Max: 100
applicationGuid string Optional Unique identifier of the application to filter results by. If omitted, scheduled runs for all applications under the account are returned.

Pagination

Use pageNumber and pageSize to page through large result sets. The response includes a totalRecordsFound field you can use to calculate the total number of pages.

Default page size 20 records per page Maximum page size 100 records per page (values above 100 are capped automatically) First page pageNumber=1

To calculate total pages from the response:

totalPages = ceil(totalRecordsFound / pageSize)

Example:
  totalRecordsFound = 135
  pageSize          = 20
  totalPages        = ceil(135 / 20) = 7

To iterate through all pages:

Example request cURL
curl --location \
  'https://<base-url>/reports-microservice/schedule-report/fetch-scheduled-runs\
?fromDate=2026-03-20%2000%3A45\
&endDate=2026-04-03%2012%3A37\
&pageNumber=1\
&pageSize=20\
&applicationGuid=YOUR_APPLICATION_GUID' \
  --header 'x-sofy-auth-key: YOUR_AUTH_KEY'

Note : Replace YOUR_AUTH_KEY and YOUR_APPLICATION_GUID with your actual values. Date values in the URL must be URL-encoded — spaces become %20 and colons become %3A.

A successful request returns a 200 OK with a JSON object containing pagination metadata and an array of scheduled run records.

Response
{
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecordsFound": 135,
  "totalRecordsFetched": 20,
  "data": [
    { ...run record }
  ]
}
Understanding the Test Run Status