Schedule activities

List Schedule Activities

Retrieves the schedule activities of your sites together with their current and historical progress, so you can report progress per component type and region in your own tools. The quantities are the same as in the platform’s schedule activity progress table.

By default only leaf activities are returned (activities without sub-activities). Set include_groups=true to also get the group activities (activities with sub-activities), so you can rebuild the full hierarchy and roll progress up yourself with each activity’s weight. Each activity carries the ID of its parent and a type (LEAF or GROUP). A group activity’s progress is a weighted percentage of its sub-activities, not a quantity, so group rows have no quantities.

Endpoint: GET /scheduleActivities

Authentication: Required (API Key)

Query Parameters

Parameter	Type	Required	Description
site_id	integer[]	No	Filter by one or more site IDs (the id field of List Sites). At most 200. Recommended, see the note below.
schedule_id	integer[]	No	Filter by one or more schedule IDs. At most 200.
schedule_is_default	boolean	No	true for only the default schedule of each site (the one marked with a star in the platform), false for only the others.
include_groups	boolean	No	true to also return the group activities, see Group activities. Defaults to false.
dataset_id	integer[]	No	Filter by one or more linked component datasets (the id field of List Datasets). At most 200.
region_id	integer[]	No	Filter by one or more regions. At most 200.
progress_last_changed_on_from	date	No	Only activities whose last completion date is on or after this date (YYYY-MM-DD).
progress_last_changed_on_to	date	No	Only activities whose last completion date is on or before this date (YYYY-MM-DD).
_page	integer	No	Page number (positive integer, defaults to 1)
_pageSize	integer	No	Number of activities per page (positive integer, defaults to 10, max 10,000)
_sortBy	string	No	Sort order. Format: +field (ascending) or -field (descending). Sortable fields: id, schedule_id, name. Default: +id

Performance: every request, including every page, recalculates the progress of all schedules in scope. Filter by site_id (and schedule_is_default=true when you only need the default schedule) and use a large _pageSize (for example 10,000) to keep requests fast and the number of pages low.

Boolean parameters: schedule_is_default and include_groups take a single true or false (not a list).

Default schedule filter: schedule_is_default=true combines with site_id and schedule_id, so site_id=123&schedule_is_default=true returns the activities of site 123’s default schedule only. A site without a default schedule returns no activities for schedule_is_default=true.

Last completion date filter: progress_last_changed_on_from / _to filter on the last date with a non-zero completed quantity, not on any change to the activity. They miss progress that went down (for example a component that was reverted), activities that were newly linked to a dataset, and target changes. Leaf activities without any completed quantity are left out as soon as either bound is set (group activities are always returned, see Group activities). To get a complete picture, fetch all activities of a site again rather than relying on this filter.

Sorting by name: names are compared case-sensitively by character code, so "Zebra" sorts before "apple" and accented letters sort after z. Activities with the same value are ordered by id.

Note: in a URL a literal + decodes to a space, so an ascending _sortBy must be percent-encoded as %2B (_sortBy=%2Bname), or simply omitted for the default.

Group activities

With include_groups=true, every group activity of the schedules in scope is returned with type GROUP, alongside the leaf activities with type LEAF:

• Group rows have the same fields as leaf rows. dataset_id, dataset_name, region_id, region_name, unit, target_quantity, completed_quantity and progress_last_changed_on are null, and progress_history is empty.
• The dataset_id, region_id and last completion date filters only apply to leaf activities. Groups are always returned in full, so the hierarchy can be rebuilt: an incremental pull with progress_last_changed_on_from returns every group each time (and is never empty), and with a dataset or region filter you also get the groups of branches without matching leaf activities.
• Group and leaf activities are sorted and paged together and both count in rowCount. Fetch all pages before rebuilding the hierarchy.
• To roll up progress the way the platform does, compute each group’s percentage complete from its direct children that count: Σ (weight × percentage) / Σ weight. A leaf counts when its target_quantity and weight are non-zero, and its percentage is completed_quantity / target_quantity × 100. A sub-group counts when its weight is non-zero and at least one of its own children counts, and its percentage is its own rolled-up percentage.
  • Children that do not count are left out of both the sum and the total weight.
  • If none of a group’s children counts, the group has no progress (the platform shows “-”), and it does not count in its own parent.
  • The roll-up is not capped at 100%. Compute with unrounded values at every level and round only for display.

Response Format

Returns a paginated response with the following structure:

{
    "data": [
        {
            "type": "LEAF | GROUP",
            "id": "integer",
            "name": "string",
            "parent_schedule_activity_id": "integer | null",
            "schedule_id": "integer",
            "schedule_name": "string",
            "schedule_is_default": "boolean",
            "weight": "number",
            "order_index": "integer",
            "dataset_id": "integer | null",
            "dataset_name": "string | null",
            "region_id": "integer | null",
            "region_name": "string | null",
            "unit": "string | null",
            "target_quantity": "number | null",
            "completed_quantity": "number | null",
            "progress_last_changed_on": "date | null",
            "progress_history": [
                {
                    "date": "date",
                    "quantity": "number",
                    "cumulative_quantity": "number"
                }
            ]
        }
    ],
    "pagination": {
        "rowCount": "integer",
        "pageCount": "integer",
        "page": "integer",
        "pageSize": "integer"
    }
}

Response Fields

• type: LEAF for an activity without sub-activities, GROUP for an activity with sub-activities (only returned with include_groups=true)
• id: Integer ID of the schedule activity
• name: Name of the activity
• parent_schedule_activity_id: Integer ID of the group activity this activity belongs to, or null for a top-level activity. Group activities themselves are only returned with include_groups=true.
• schedule_id / schedule_name: The schedule the activity belongs to
• schedule_is_default: true when the schedule is the default schedule of its site
• weight: How much the activity counts in its parent’s progress, relative to its siblings (the activities with the same parent; top-level activities are siblings at the schedule root). Defaults to 1. 0 means the activity does not count; if all siblings weigh 0, their parent shows no progress. The platform weighs each sibling’s percentage complete, not its raw quantities, so siblings in different units can be combined. A group’s percentage is weighed into its own parent the same way.
• order_index: The order of the activity among its siblings. Only meaningful relative to its siblings: the values are not necessarily contiguous and need not start at 0.
• dataset_id / dataset_name: The component dataset (component type) the activity tracks progress from, or null when it is not linked to one. dataset_id matches the id field of List Datasets. null for a group activity.
• region_id / region_name: The region the activity is limited to, or null when it is not limited to a region. region_name is also null when the region has no name or no longer exists. null for a group activity.
• unit: The unit of the quantities, or null when the activity has no unit. For an activity that counts components, the unit is the name of the linked dataset in lowercase, so it changes when the dataset is renamed. A unit literally named “units” is also returned as null. null for a group activity.
• target_quantity: The planned total quantity, 0 when no target is set. null for a group activity.
• completed_quantity: The completed quantity to date. null for a group activity.
• progress_last_changed_on: The last completion date: the last date (YYYY-MM-DD, UTC, today or earlier) with a non-zero completed quantity, or null when nothing has been completed yet or for a group activity
• progress_history: The completed quantity per date, oldest first. quantity is the amount completed on that date, cumulative_quantity the total up to and including that date. Use it to build an S-curve.
• pagination: The standard pagination object

Example Requests

List all schedule activities of a site:

curl -X GET "https://api.sitemark.com/scheduleActivities?site_id=123&_pageSize=10000" \
  -H "Authorization: ApiKey your-api-key-here"

Progress of one component type in one region:

curl -X GET "https://api.sitemark.com/scheduleActivities?site_id=123&dataset_id=456&region_id=789" \
  -H "Authorization: ApiKey your-api-key-here"

The full hierarchy of the default schedule of a site:

curl -X GET "https://api.sitemark.com/scheduleActivities?site_id=123&schedule_is_default=true&include_groups=true&_pageSize=10000" \
  -H "Authorization: ApiKey your-api-key-here"

Example Response

{
    "data": [
        {
            "type": "GROUP",
            "id": 1200,
            "name": "Piling",
            "parent_schedule_activity_id": null,
            "schedule_id": 31,
            "schedule_name": "Construction schedule",
            "schedule_is_default": true,
            "weight": 1,
            "order_index": 0,
            "dataset_id": null,
            "dataset_name": null,
            "region_id": null,
            "region_name": null,
            "unit": null,
            "target_quantity": null,
            "completed_quantity": null,
            "progress_last_changed_on": null,
            "progress_history": []
        },
        {
            "type": "LEAF",
            "id": 1201,
            "name": "Install piles - Block A",
            "parent_schedule_activity_id": 1200,
            "schedule_id": 31,
            "schedule_name": "Construction schedule",
            "schedule_is_default": true,
            "weight": 2,
            "order_index": 1,
            "dataset_id": 456,
            "dataset_name": "Piles",
            "region_id": 789,
            "region_name": "Block A",
            "unit": "piles",
            "target_quantity": 1200,
            "completed_quantity": 300,
            "progress_last_changed_on": "2026-01-16",
            "progress_history": [
                { "date": "2026-01-15", "quantity": 120, "cumulative_quantity": 120 },
                { "date": "2026-01-16", "quantity": 180, "cumulative_quantity": 300 }
            ]
        }
    ],
    "pagination": {
        "rowCount": 2,
        "pageCount": 1,
        "page": 1,
        "pageSize": 10
    }
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
400	Bad Request - More than 200 ids, an invalid date or boolean, an unsortable _sortBy field, or an unsupported parameter
429	Too Many Requests - A rate limit was exceeded
500	Internal Server Error

Note: Activities on schedules you do not have access to are left out of the response; they do not cause an error.