Run route scanning asynchronously.
POST /v1/jobs/route-scan
Scope charts:write · Cost 8 requests · Plans Scale and Enterprise
Creates a durable route-scan job, retries once on processing failure, and optionally calls your callback URL at completion.
Send your key in one header: X-RailCore-Key, Authorization: Bearer or X-Api-Key. Two headers with different keys answer 401 AMBIGUOUS_API_KEY. This operation requires the charts:write scope. Growth, Scale and Enterprise keys must also sign every request with HMAC-SHA256, sending X-RailCore-Timestamp, X-RailCore-Nonce and X-RailCore-Signature. Free and Starter keys send the key alone. See the authentication guide and HMAC signing.
This operation takes no path or query parameters.
| Field | Type | Description |
|---|---|---|
from | string | Boarding station code or station name. |
to | string | Destination station code or station name. |
date | string(date) | Journey date in YYYY-MM-DD. |
quota | Quota | Reservation quota, default GN. |
max_trains | integer | Maximum trains to scan, 1 to 100. |
min_score | number | Drop matches scoring below 0 to 100. |
only_running | boolean | Keep only trains that run on the requested day. |
only_chart_prepared | boolean | Keep only trains with a prepared chart. |
sort_by | string | departure, departure_desc, duration, score, or chart_ready. |
include_detail | boolean | Include the full hopping result per train. |
train_types | string | Comma-separated train-type allow list. |
avoid_train_types | string | Comma-separated train-type deny list. |
max_hops | integer | Maximum hopping chain length, 1 to 12. |
prefer_berth / avoid_berth | string | Comma-separated berth preference codes. |
prefer_class / avoid_class | string | Comma-separated class preference codes. |
include_fare | boolean | Decorate direct and hopping options with fare data. |
include_alternate_boarding | boolean | Evaluate nearby boarding points. |
strategies | string | min_hops, min_seat_changes, cheapest, or all. |
alternate_boarding_mode | string | lightweight or extended. |
alternate_boarding_max_candidates | integer | Extended candidate cap, 1 to 5. |
include_cross_class | boolean | Allow a plan that changes class between hops. |
callback_url | string(uri) | Optional. Where RailCore POSTs the job's outcome when it finishes, signed with the webhook_secret this request returns. An https URL on a public host, port 443 or 1024 and up, with no user name or password. localhost, private, link-local, CGNAT and cloud metadata addresses are refused with 400 VALIDATION_ERROR (details[].field callback_url). See the webhooks guide. |
Base URL https://ir.railcore.tech/v1. Keep the key in an environment variable and call from a trusted server-side environment.
RUN_DATE=$(TZ=Asia/Kolkata date +%F)
curl -sS -X POST \
-H "X-RailCore-Key: $RAILCORE_KEY" \
-H "Content-Type: application/json" \
--data '{"from":"BSL","to":"ADI","date":"'"$RUN_DATE"'","quota":"GN","max_trains":"8","only_running":"true","include_fare":"false","prefer_class":"3A,2A"}' \
"https://ir.railcore.tech/v1/jobs/route-scan"
const runDate = new Intl.DateTimeFormat("en-CA", { timeZone: "Asia/Kolkata" }).format(new Date());
const response = await fetch("https://ir.railcore.tech/v1/jobs/route-scan", {
method: "POST",
headers: {
"X-RailCore-Key": process.env.RAILCORE_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"from": "BSL",
"to": "ADI",
"date": runDate,
"quota": "GN",
"max_trains": "8",
"only_running": "true",
"include_fare": "false",
"prefer_class": "3A,2A"
}),
});
const body = await response.json();
console.log(response.status, body);
import datetime
import os
import requests
run_date = datetime.datetime.now(datetime.timezone(datetime.timedelta(hours=5, minutes=30))).date().isoformat()
response = requests.request(
"POST",
"https://ir.railcore.tech/v1/jobs/route-scan",
headers={"X-RailCore-Key": os.environ["RAILCORE_KEY"]},
json={"from": "BSL", "to": "ADI", "date": run_date, "quota": "GN", "max_trains": "8", "only_running": "true", "include_fare": "false", "prefer_class": "3A,2A"},
timeout=20,
)
print(response.status_code, response.json())
This operation counts as 8 requests and is available on Scale and Enterprise. Failed requests are free. Per-minute budgets, daily caps and the headers reporting what is left are in rate limits; plans and prices are in requests and billing.
| Field | Type | Description |
|---|---|---|
job_id | string | Use this identifier for polling, streaming, or cancellation. |
status | processing | Initial job state. |
poll_url | string | Relative polling endpoint. |
stream_url | string | Relative SSE endpoint. |
message | string | Submission summary. |
webhook_secret | string | Present when you gave a callback_url: the secret (whsec_…) that signs this job's callbacks. It is shown once and RailCore does not store it, so save it with the job_id. |
{
"success": true,
"data": {
"job_id": "job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
"status": "processing",
"poll_url": "/v1/jobs/job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
"stream_url": "/v1/jobs/job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8/stream",
"message": "Route scan submitted. Poll the poll_url for results."
},
"meta": {
"api_version": "v1",
"request_id": "req_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
"trace_id": "trc_01J5Z7Y8N2K4M6P8R0T2V4X6Z9",
"timestamp": "2026-11-20T10:57:05.609Z",
"freshness": {
"mode": "live",
"retrieved_at": "2026-11-20T10:57:05.609Z",
"sources": [
{
"confidence": "high"
}
]
}
}
}
| Status | Code | Description | Retry |
|---|---|---|---|
| 400 | VALIDATION_ERROR | A required field is missing or invalid, or callback_url is not an https URL on a public host. error.details[].field names the field. Not counted. | Not retryable |
| 429 | JOB_LIMIT_EXCEEDED | Five jobs are already active on this account, across all of its keys. | Retryable |
| 401 | MISSING_API_KEY | No key in X-RailCore-Key, Authorization: Bearer or X-Api-Key, or the key is too short. | Not retryable |
| 401 | INVALID_API_KEY | The key is unknown or revoked. A disabled or expired key answers API_KEY_DISABLED or API_KEY_EXPIRED. | Not retryable |
| 401 | AMBIGUOUS_API_KEY | More than one key header was sent, with different keys. Send the key in one header. | Not retryable |
| 401 | SIGNATURE_INVALID | HMAC signature missing or not verified. Growth, Scale and Enterprise keys must sign every request; a key with no signing secret must be rotated. | Not retryable |
| 403 | SCOPE_MISSING | The key lacks this operation's scope. | Not retryable |
| 403 | PLAN_ENDPOINT_DISABLED | The account's plan does not include this endpoint. | Not retryable |
| 402 | CREDITS_EXHAUSTED | The month's requests are used up, or too few are left for this request. Nothing is fetched. | Not retryable |
| 429 | RATE_LIMITED | The account's per-minute budget, or a Free account's daily budget, is used up. Every key on the account shares it. Honor Retry-After. | Retryable |
| 410 | API_VERSION_SUNSET | This API version has reached its announced sunset date. Migrate to a supported major version. | Not retryable |
| 503 | UPSTREAM_UNAVAILABLE | Live data could not be retrieved. Wait for Retry-After, then retry with backoff. Not counted. | Retryable |
| 503 | UPSTREAM_TIMEOUT | The live-data request ran past its deadline. Wait for Retry-After, then retry with backoff. Not counted. | Retryable |
| 503 | METERING_UNAVAILABLE | The request could not be counted, so no data was returned. Retry with backoff. | Retryable |
All RailCore Indian Railways API endpoints · Quickstart · Rate limits
Last updated