---
title: "Several reads in one round trip"
method: POST
path: "/api/batch"
tags: ["Directory"]
---

# Several reads in one round trip

`POST /api/batch`

## Request

- Base URL: `https://youspot.com`
- URL: `https://youspot.com/api/batch`
- Auth: none required

Runs up to 20 GET requests against the read endpoints and answers each with its own status and body, in the order sent. The batch itself is 200 once the envelope is valid, even when every item failed, so read each item's `status`. An item naming anything that is not a batchable read is refused on its own with `allowed_paths` attached; the others still run.

Each item is dispatched in-process to the endpoint it names, with your `Authorization` and `Cookie` forwarded, so a sub-response is exactly what that endpoint would have returned on its own. Each item counts against its endpoint's own rate limit; the batch saves round trips, not budget.

## Request body

- BatchRequest
  - `requests` object[], required
    - `id` string: Echoed on the matching response. Defaults to the item's position.
    - `method` 'GET'
    - `path` string, required: One of the batchable reads: `/api/network/members`, `/api/human/{username}` (with or without `.json` or `.md`), `/api/jobs/{job_id}`, the MCP cards at `/mcp`, `/mcp/v1` and `/mcp/sandbox`, `/.well-known/mcp/server-card.json`, `/.well-known/api-catalog`, the two OAuth metadata documents, and `/auth.md`.
    - `query` object: Query parameters for the item, as the endpoint documents them.

## Response `200`

Every sub-response, in request order.

- BatchResponse
  - `object` 'batch', required
  - `count` integer, required
  - `responses` object[], required
    - `id` string, required
    - `status` integer, required: The HTTP status the endpoint answered.
    - `content_type` string
    - `body` object: The parsed JSON body, when the endpoint answered JSON.
    - `text` string: The body as text, when it was not JSON.

## Other responses

- `400`: The request was refused. `error` is stable; read `error_description` for the reason.
- `429`: Too many batches from this address in the current window.

---

[API](https://skmtc.dev/youspot/apis/youspot-http-api.md) · [All operations](https://skmtc.dev/youspot/apis/youspot-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/youspot/apis/youspot-http-api/revisions/6615ad5d017d?raw)