API reference · v1
Next cron run times
Validate a five-field cron expression (or @hourly/@daily/@weekly/@monthly/@yearly) and list its next run times in an IANA time zone. Missing wall times during DST spring-forward are skipped and repeated wall times during fall-back run twice. Runs strictly after startAt (default: now) and before startAt + windowDays. mode sets the day-of-month/day-of-week rule: generic (Vixie cron: OR when both fields are restricted), and, or. Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx/5xx.
/v1/run/cron/nextAccess requirements
Health, metadata, changelog and waitlist routes are public. Catalog reads (GET /v1/tools, /v1/tools/{id}, /v1/colors/*) and POST /v1/tools/query require a tools.read credential; POST /v1/run/* requires tools.run. There is no anonymous access to these routes: send an API key (Bearer OR X-API-Key) from your server, or use the HttpOnly main-site session plus workspace selection and same-origin Origin. Never combine credentials. Every admitted call is metered. Ingress and workspace/actor minute/month limits are separate; waitlist has its own policy.
Implemented interfaces and development screens do not imply public production availability, paid access or a completed payment integration. Confirm access with Birdor before connecting an application. No paid Pro service, activation or cross-device sync is currently delivered. We are validating one repeatable task before building a paid offer.
Parameters
| Field | Description |
|---|---|
AuthorizationstringOptional | Bearer API key with tools.run; alternatively X-API-Key. One of the credentials is required. |
X-API-KeystringOptional | Alternative to Authorization; never send both. |
X-Birdor-Workspace-IDstringOptional | Required with the site session; optional and matching with an API key. |
X-Birdor-Project-IDstringOptional | Optional owned project; a project-bound key cannot select another project. |
Request body
Send JSON with Content-Type: application/json.
| Field | Description |
|---|---|
expressionstringRequired | Five-field cron expression or @hourly/@daily/@weekly/@monthly/@yearly; at most 128 characters. Seconds fields are not supported. |
timeZonestringOptional | IANA time zone such as America/New_York; default UTC. |
startAtstringOptional | RFC 3339 instant with Z or an explicit offset; runs are strictly after it. Default: request time. |
countintegerOptional | Number of runs to return, 1–100; default 10. |
windowDaysintegerOptional | Search window after startAt in days, 1–365; default 365. |
modegeneric | and | orOptional | Day-of-month/day-of-week rule: generic (OR when both are restricted, like Vixie cron), and, or. |
Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/run/cron/next" \
--header "Accept: application/json" \
--header "Authorization: Bearer $BIRDOR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"expression": "0 9 * * 1-5",
"timeZone": "America/New_York",
"startAt": "2026-10-09T12:00:00Z",
"count": 2
}'Examples are copied only; this page does not send API requests.
Responses
Illustrative response. Values vary by environment and time.
200Success
{
"ok": true,
"data": {
"expression": "0 9 * * 1-5",
"timeZone": "America/New_York",
"mode": "generic",
"description": {
"minute": "Custom minute pattern: 0",
"hour": "Custom hour pattern: 9",
"dayOfMonth": "Every day of the month",
"month": "Every month",
"dayOfWeek": "Custom day of week range: 1-5"
},
"explanation": {
"dialect": "standard",
"time": {
"kind": "clock",
"times": [
{
"hour": 9,
"minute": 0
}
]
},
"days": {
"kind": "dow",
"dow": {
"kind": "range",
"from": 1,
"to": 5
}
},
"months": {
"kind": "all"
}
},
"runs": [
{
"utc": "2026-10-09T13:00:00.000Z",
"local": "2026-10-09T09:00:00-04:00"
},
{
"utc": "2026-10-12T13:00:00.000Z",
"local": "2026-10-12T09:00:00-04:00"
}
],
"status": "count-reached",
"startAt": "2026-10-09T12:00:00.000Z",
"windowEnd": "2027-10-09T12:00:00.000Z"
},
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}400Invalid JSON, schema validation failure (field paths/codes only, never input values) or ambiguous credentials
{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}401Missing, expired, rotated, revoked or invalid credential; there is no anonymous access
{
"ok": false,
"code": "UNAUTHENTICATED",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}403Key lacks tools.run, or workspace/project/member policy or site Origin denied
{
"ok": false,
"code": "FORBIDDEN",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}405Only POST is supported; rejected before admission
{
"ok": false,
"code": "METHOD_NOT_ALLOWED",
"message": "Method not allowed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}408Body read exceeds five seconds; before admission
{
"ok": false,
"code": "REQUEST_TIMEOUT",
"message": "Request body timeout or aborted",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}413Body exceeds 1024 bytes; before admission
{
"ok": false,
"code": "PAYLOAD_TOO_LARGE",
"message": "Request body too large",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}415Content-Type must be application/json; before admission
{
"ok": false,
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "JSON content type required",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}429Ingress, workspace/actor minute or monthly quota exceeded; inspect code and Retry-After
{
"ok": false,
"code": "QUOTA_EXCEEDED",
"message": "API request limit exceeded",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}500Unexpected operation failure; details are never echoed
{
"ok": false,
"code": "OPERATION_FAILED",
"message": "Operation failed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}503Authentication/metering dependency unavailable
{
"ok": false,
"code": "API_GATEWAY_UNAVAILABLE",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}422INVALID_CRON_EXPRESSION: Expression cannot be parsed; details.reason explains which field; INVALID_TIME_ZONE: timeZone is not a supported IANA time zone; INVALID_START_AT: startAt is outside 1970-01-01 to 2099-01-01 or not a valid instant
{
"ok": false,
"code": "INVALID_CRON_EXPRESSION",
"message": "Expression cannot be parsed; details.reason explains which field",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}Example response fields
Fields shown in this example; optional fields can be omitted. Array rows describe the first example element.
- okboolean
- Application success flag.
- dataobject
- Endpoint-specific result.
- data.expressionstring
- Normalized cron expression (macros expanded).
- data.timeZonestring
- IANA time zone used for wall times.
- data.modestring
- Day-of-month/day-of-week rule applied.
- data.descriptionobject
- Resource description.
- data.description.minutestring
- Minute field explanation.
- data.description.hourstring
- Hour field explanation.
- data.description.dayOfMonthstring
- Day-of-month field explanation.
- data.description.monthstring
- Month field explanation.
- data.description.dayOfWeekstring
- Day-of-week field explanation.
- data.explanationobject
- Endpoint-specific example value.
- data.explanation.dialectstring
- Endpoint-specific example value.
- data.explanation.timeobject
- Endpoint-specific example value.
- data.explanation.time.kindstring
- Endpoint-specific example value.
- data.explanation.time.timesarray
- Endpoint-specific example value.
- data.explanation.daysobject
- Endpoint-specific example value.
- data.explanation.days.kindstring
- Endpoint-specific example value.
- data.explanation.days.dowobject
- Endpoint-specific example value.
- data.explanation.monthsobject
- Endpoint-specific example value.
- data.explanation.months.kindstring
- Endpoint-specific example value.
- data.runsarray
- Upcoming runs in chronological order.
- data.runs[].utcstring
- Run instant in UTC (ISO 8601).
- data.runs[].localstring
- Run wall time with the zone offset at that instant (RFC 3339).
- data.statusstring
- Operation result.
- data.startAtstring
- Instant after which runs are listed.
- data.windowEndstring
- End of the search window (exclusive).
- request_idstring
- Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
- timestampstring
- Response creation timestamp.