Submit hopping job

Run berth-hopping analysis asynchronously.

POST /v1/jobs/hopping

Scope charts:write · Credits 10 at submission · Plans Scale and Enterprise

Creates a durable train-specific hopping job with optional completion callback and one automatic retry.

Authentication

Send your key in the X-RailCore-Key header. This operation requires the charts:write scope. See the authentication guide.

Request parameters

This operation takes no path or query parameters.

JSON body

Field	Type	Description
`train_number`	`string`	Train to analyze.
`from`	`string`	Boarding station code.
`to`	`string`	Destination station code.
`date`	`string(date)`	Journey date in YYYY-MM-DD.
`quota`	`Quota`	Reservation quota, default GN.
`via`	`string`	Comma-separated stations the plan must cross.
`max_hops`	`integer`	Maximum 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`	Add fare details.
`include_alternate_boarding`	`boolean`	Evaluate nearby boarding stations.
`include_cross_class`	`boolean`	Allow class changes between hops.
`strategies`	`string`	min_hops, min_seat_changes, cheapest, or all.
`callback_url`	`string(uri)`	Optional HTTPS endpoint that receives terminal status and result or error.

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

curl -sS -X POST \
  -H "X-RailCore-Key: $RAILCORE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"train_number":"12656","from":"BSL","to":"ADI","date":"2026-08-27","quota":"GN","max_hops":"6","include_fare":"true","prefer_class":"3A"}' \
  "https://ir.railcore.tech/v1/jobs/hopping"

JavaScript

const response = await fetch("https://ir.railcore.tech/v1/jobs/hopping", {
  method: "POST",
  headers: {
    "X-RailCore-Key": process.env.RAILCORE_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "train_number": "12656",
  "from": "BSL",
  "to": "ADI",
  "date": "2026-08-27",
  "quota": "GN",
  "max_hops": "6",
  "include_fare": "true",
  "prefer_class": "3A"
}),
});

const body = await response.json();
console.log(response.status, body);

Python

import json
import os
import requests

response = requests.request(
    "POST",
    "https://ir.railcore.tech/v1/jobs/hopping",
    headers={"X-RailCore-Key": os.environ["RAILCORE_KEY"]},
    json=json.loads("{\"train_number\":\"12656\",\"from\":\"BSL\",\"to\":\"ADI\",\"date\":\"2026-08-27\",\"quota\":\"GN\",\"max_hops\":\"6\",\"include_fare\":\"true\",\"prefer_class\":\"3A\"}"),
    timeout=20,
)
print(response.status_code, response.json())

Rate limits and credits

This call costs 10 at submission credits and is available on Scale and Enterprise. Per-minute and daily budgets, and the headers reporting remaining quota, are documented in rate limits and credits and billing.

Response fields

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.

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": "Hopping analysis submitted. Poll the poll_url for results."
  },
  "meta": {
    "api_version": "v1",
    "request_id": "req_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "trace_id": "trc_01J5Z7Y8N2K4M6P8R0T2V4X6Z9",
    "timestamp": "2026-08-20T17:12:23.305Z",
    "freshness": {
      "mode": "live",
      "retrieved_at": "2026-08-20T17:12:23.305Z",
      "sources": [
        {
          "confidence": "high"
        }
      ]
    }
  }
}

Errors

Status	Code	Description	Retry
429	`JOB_LIMIT_EXCEEDED`	Five jobs are already active for this API key.	Retryable
400	`VALIDATION_ERROR`	A required field is missing or invalid.	Not retryable
401	`MISSING_API_KEY / INVALID_API_KEY`	The credential is absent, unknown, disabled, or expired.	Not retryable
403	`SCOPE_MISSING / PLAN_ENDPOINT_DISABLED`	The key lacks the required scope or plan entitlement.	Not retryable
402	`CREDITS_EXHAUSTED`	The account balance cannot cover this operation.	Not retryable
429	`RATE_LIMITED`	Minute or daily request budget is exhausted. 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
502	`UPSTREAM_UNAVAILABLE`	Live data could not be retrieved. Retry with backoff.	Retryable
504	`UPSTREAM_TIMEOUT`	The live-data request exceeded its deadline. Retry with backoff.	Retryable
503	`METERING_UNAVAILABLE`	Credit settlement is temporarily unavailable and no data was returned.	Retryable

Related Jobs endpoints

All RailCore Indian Railways API endpoints · Quickstart · Rate limits