GET `/api/v1/batches/{id}`

A batch's status and counts.

Scope data:read
Legacy keys
operationId dataBatch

The token needs the scope data:read, and the person or service account behind it needs the matching privileges and account permissions, exactly as on the screens. See Scopes.

Legacy keys. Also accepts the deprecated legacy data API keys (vst_…), with Deprecation and Sunset headers. Move to a service account.

Request

GET /api/v1/batches/{id}

Path parameters

Name	Description	Example
`id`	The id of the batche.	`311`

Headers

Header	Required	Value
`Authorization`	yes	`Bearer <token>`: an OAuth access token (`vat_…`) or a personal access token (`vpt_…`), or a legacy key (`vst_…`, deprecated). Get a token

Examples

Keep the token in an environment variable (VESTORIS_TOKEN), never in the script.

curl

curl "https://vestoris.com/api/v1/batches/311" \
  -H "Authorization: Bearer $VESTORIS_TOKEN"

Python (requests)

import os, requests

r = requests.get(
    "https://vestoris.com/api/v1/batches/311",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()  # errors are application/problem+json with a stable "code"
print(r.json())

JavaScript (fetch)

const res = await fetch("https://vestoris.com/api/v1/batches/311", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.detail}`); // problem+json
console.log(data);

Response

200 OK, application/json: LegacyBatchStatus. Rate-limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Response fields

Field	Type	Description
`ok`	boolean	Ok.
`batch`	object	The batch the file became.
`batch.id`	integer	The record's id (a string of digits).
`batch.dataset`	string	The data set: securities, accounts, positions, lots, cash, prices, fx, corporate_actions, issuers, brokers, benchmarks…
`batch.status`	string	The status.
`batch.file_name`	string	The file's name.
`batch.sha256`	string or null	SHA-256 of the file.
`batch.business_date`	string or null	The business date the data is for (YYYY-MM-DD).
`batch.counts`	any	Rows by outcome: new, changed, unchanged, rejected, deleted.
`batch.message`	string or null	A message in plain words.
`batch.hold_reason`	string or null	Why the batch is held for review.
`batch.created_at`	string or null	When it was created.
`batch.applied_at`	string or null	When it was applied.
`progress`	object	Progress of a long operation.
`progress.rows`	integer	Number of rows.
`progress.total`	integer	Total.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "batch": {
        "id": 1,
        "dataset": "prices",
        "status": "active",
        "file_name": "ACME_PRICE_20261027_001.xml",
        "sha256": "e3b0…",
        "business_date": "2026-10-27",
        "counts": {
            "new": 3,
            "changed": 12,
            "unchanged": 580,
            "rejected": 1
        },
        "message": "",
        "hold_reason": null,
        "created_at": "2026-10-27T14:30:00Z",
        "applied_at": "2026-10-27T14:30:00Z"
    },
    "progress": {
        "rows": 612,
        "total": 612
    }
}

Example values. Your values depend on your firm's data; prices, orders and fills are simulated.

Status codes and errors

Errors are application/problem+json (RFC 9457) with a stable code to program against; the detail says what to fix. See Errors.

Status	When	Problem codes
200	Success
400	The request is malformed	`invalid_request`
401	No token, or it is invalid or expired	`invalid_token`
403	The token lacks the scope, or the person or service account behind it lacks the privilege or account permission	`insufficient_scope` `forbidden` `ip_not_allowed` `legacy_keys_disabled`
404	Not found, or not visible to you (the API never confirms what you may not see)	`not_found`
429	Rate limited: wait for Retry-After seconds	`rate_limited`

{
    "type": "https://vestoris.com/developers/errors#validation_failed",
    "title": "Validation failed",
    "status": 422,
    "detail": "Quantity must be greater than zero.",
    "code": "validation_failed",
    "instance": "/api/v1/batches/311"
}

On the screens

The same thing in the app is explained in: