Submit route-scan job

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.

Authentication

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.

Request parameters

This operation takes no path or query parameters.

JSON body

FieldTypeDescription
fromstringBoarding station code or station name.
tostringDestination station code or station name.
datestring(date)Journey date in YYYY-MM-DD.
quotaQuotaReservation quota, default GN.
max_trainsintegerMaximum trains to scan, 1 to 100.
min_scorenumberDrop matches scoring below 0 to 100.
only_runningbooleanKeep only trains that run on the requested day.
only_chart_preparedbooleanKeep only trains with a prepared chart.
sort_bystringdeparture, departure_desc, duration, score, or chart_ready.
include_detailbooleanInclude the full hopping result per train.
train_typesstringComma-separated train-type allow list.
avoid_train_typesstringComma-separated train-type deny list.
max_hopsintegerMaximum hopping chain length, 1 to 12.
prefer_berth / avoid_berthstringComma-separated berth preference codes.
prefer_class / avoid_classstringComma-separated class preference codes.
include_farebooleanDecorate direct and hopping options with fare data.
include_alternate_boardingbooleanEvaluate nearby boarding points.
strategiesstringmin_hops, min_seat_changes, cheapest, or all.
alternate_boarding_modestringlightweight or extended.
alternate_boarding_max_candidatesintegerExtended candidate cap, 1 to 5.
include_cross_classbooleanAllow a plan that changes class between hops.
callback_urlstring(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.

Code examples

Base URL https://ir.railcore.tech/v1. Keep the key in an environment variable and call from a trusted server-side environment.

cURL

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"

JavaScript

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);

Python

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())

Rate limits and cost

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.

Response fields

FieldTypeDescription
job_idstringUse this identifier for polling, streaming, or cancellation.
statusprocessingInitial job state.
poll_urlstringRelative polling endpoint.
stream_urlstringRelative SSE endpoint.
messagestringSubmission summary.
webhook_secretstringPresent 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.

Example response

{
  "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"
        }
      ]
    }
  }
}

Errors

StatusCodeDescriptionRetry
400VALIDATION_ERRORA 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
429JOB_LIMIT_EXCEEDEDFive jobs are already active on this account, across all of its keys.Retryable
401MISSING_API_KEYNo key in X-RailCore-Key, Authorization: Bearer or X-Api-Key, or the key is too short.Not retryable
401INVALID_API_KEYThe key is unknown or revoked. A disabled or expired key answers API_KEY_DISABLED or API_KEY_EXPIRED.Not retryable
401AMBIGUOUS_API_KEYMore than one key header was sent, with different keys. Send the key in one header.Not retryable
401SIGNATURE_INVALIDHMAC 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
403SCOPE_MISSINGThe key lacks this operation's scope.Not retryable
403PLAN_ENDPOINT_DISABLEDThe account's plan does not include this endpoint.Not retryable
402CREDITS_EXHAUSTEDThe month's requests are used up, or too few are left for this request. Nothing is fetched.Not retryable
429RATE_LIMITEDThe 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
410API_VERSION_SUNSETThis API version has reached its announced sunset date. Migrate to a supported major version.Not retryable
503UPSTREAM_UNAVAILABLELive data could not be retrieved. Wait for Retry-After, then retry with backoff. Not counted.Retryable
503UPSTREAM_TIMEOUTThe live-data request ran past its deadline. Wait for Retry-After, then retry with backoff. Not counted.Retryable
503METERING_UNAVAILABLEThe request could not be counted, so no data was returned. Retry with backoff.Retryable

Implementation notes

Related Jobs endpoints

All RailCore Indian Railways API endpoints · Quickstart · Rate limits

Last updated