Scheduling & Priority
Every Collection has two settings that determine when it runs and how quickly it is processed: a schedule type and a priority tier. Together they give you precise control over your scraping cadence.
Schedule types
MultiCartAPI supports five schedule types. Choose Manual if you want to trigger runs yourself via the API or dashboard; choose one of the automatic types to have the system run your Collection for you.
| Type | Runs when |
|---|---|
| Manual | Only when you explicitly trigger a run via the dashboard or POST /schedules/run/result/. |
| Every X Minutes | Repeatedly, at a fixed minute interval within the hours and days you specify. |
| Daily | Once per day at the hour(s) you specify, on every day of the week. |
| Weekly | Once per week at the hour(s) you specify, on the day(s) of the week you choose. |
| Monthly | Once per month at the hour(s) you specify. |
Times are UTC+10
All hours in schedule_time are interpreted as UTC+10 (Australian Eastern Standard Time). If your team works in a different timezone, adjust accordingly when setting the hours array.
The schedule_time object
When you create or update a Collection via POST /schedules/add_schedule/ or POST /schedules/update_schedule/, you pass a schedule_time object alongside the schedule string. Its shape depends on the schedule type.
Manual
No schedule_time configuration is needed. Pass an empty object or omit the field entirely.
{}Every X Minutes
Specify the repeat interval in minutes, the days of the week to run on, and the hour windows during which repeats are allowed.
{
"minutes_frequency": "30",
"days_of_week": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday"
],
"hours": [
"08.00",
"12.00",
"16.00"
]
}| Field | Type | Description |
|---|---|---|
minutes_frequency | string (numeric) | How often to repeat, in minutes. E.g. "30" runs every 30 minutes. |
days_of_week | array of strings | Days the schedule is active. Lowercase full names: "monday" through "sunday". |
hours | array of strings | Hour windows (UTC+10) during which repeats trigger. Format: "HH.MM" e.g. "08.00", "14.30". |
Daily
Specify the hour(s) each day at which the Collection should run. days_of_week is not used for Daily schedules.
{
"hours": [
"06.00",
"18.00"
]
}| Field | Type | Description |
|---|---|---|
hours | array of strings | One or more times (UTC+10) at which to run each day. Format: "HH.MM". |
Weekly
Specify both the day(s) of the week and the hour(s) within those days.
{
"days_of_week": [
"monday",
"thursday"
],
"hours": [
"02.00"
]
}| Field | Type | Description |
|---|---|---|
days_of_week | array of strings | Days of the week to run. Lowercase full names. |
hours | array of strings | Time(s) (UTC+10) within each chosen day. Format: "HH.MM". |
Monthly
Specify the hour(s) at which to run once per month. The day of the month is determined by the Collection's creation date.
{
"hours": [
"03.00"
]
}| Field | Type | Description |
|---|---|---|
hours | array of strings | Time(s) (UTC+10) at which to run on the scheduled monthly date. Format: "HH.MM". |
Full API example — creating a Weekly Collection
curl https://multicartapi.com/api/v1/schedules/add_schedule/ \
-X POST \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "AU Laptops — Weekly",
"request_type": "amazon",
"schedule": "Weekly",
"priority": "High",
"notification_email": "[email protected]",
"fetch_mode": "full",
"schedule_time": {
"days_of_week": ["monday", "thursday"],
"hours": ["02.00"]
}
}'Priority tiers
When multiple Collections are queued at the same time, priority determines the order in which the scraping workers pick them up.
| Tier | Queue position | Best used for |
|---|---|---|
| Highest | First in queue | Time-critical pricing data where every minute counts. |
| High | Second in queue | Important daily jobs that should finish before lower-priority work. |
| Normal | Default tier | Standard scheduled Collections with no special urgency. |
| Low | Fourth in queue | Background enrichment or archiving jobs. |
| Lowest | Last in queue | Bulk historical runs that can wait behind everything else. |
Priority affects queue order, not worker allocation
All tiers share the same worker fleet. Highest simply means your Collection is dequeued before High, which is dequeued before Normal, and so on. During quiet periods every priority tier runs promptly regardless.
You can change the priority of an existing Collection at any time without affecting its schedule:
POST /api/v1/schedules/update_schedule/
{
"schedule_id": 101,
"priority": "Highest"
}
Next steps