---
title: "Check many companies in one call"
method: POST
path: "/api/network/batch"
---

# Check many companies in one call

`POST /api/network/batch`

## Request

- Base URL: `https://trooth.co`
- URL: `https://trooth.co/api/network/batch`
- Auth: none required

A read of up to 25 companies in one request, for an agent that plans a sequence of steps and needs to know, before acting, what each company's record says and whether it changed since planning. Each target is a domain or profile slug, or { q, pin } where pin is the record digest from an earlier read. Each result has status (listed, not_listed, withheld, unavailable), what Trooth's own readings show, the version and SHA-256 digest of the record GET /api/network/profile serves, pin.changed when a pin was sent, and plain day counts. A target that cannot be read is that target's unavailable, with the problem registry's retryable flag and next action; the other targets are still answered. It changes nothing, so it takes no Idempotency-Key and repeating it is always safe. Nothing in it grades, ranks or certifies a company. Errors are always RFC 9457 problem details. Never cached. Readable cross-origin: the response carries Access-Control-Allow-Origin: * and never Access-Control-Allow-Credentials, so a browser on any site may read it without cookies.

## Request body

- object
  - `targets` union[], required: Domains or profile slugs, each a string or { q, pin }.
    - union
      - string: A domain or profile slug.
      - object
        - `q` string, required: A domain or profile slug.
        - `pin` string: The record digest from an earlier read.

## Response `200`

One result per target, in the order sent.

- NetworkBatch: The answer for every target, in the order sent. Canonical JSON Schema: https://trooth.co/schemas/network-batch.v1.schema.json; embedded here with its $defs as NetworkBatch_* components.
  - `format` 'trooth.network-batch.v1', required: Names this shape.
  - `checked_at` string, required: When this answer was read, ISO 8601.
  - `summary` object, required: Counts of the statuses below.
    - `targets` integer, required: Targets sent.
    - `listed` integer, required: Targets with a published record.
    - `not_listed` integer, required: Targets with no published record.
    - `withheld` integer, required: Targets withheld by an emergency restriction.
    - `unavailable` integer, required: Targets that could not be read on this call.
    - `changed_since_pin` integer, required: Targets whose pinned digest no longer matches.
  - `results` NetworkBatchItem[], required: One entry per target.
    - `target` string, required: The target as read: a domain or a profile slug.
    - `status` 'listed' | 'not_listed' | 'withheld' | 'unavailable', required: listed: a published record. not_listed: none. withheld: an emergency restriction withholds it. unavailable: it could not be read on this call, which is not a statement about the company.
    - `problem` object, nullable, required: Why this target could not be answered, from the problem registry.
      - `code` string, required: The registry code; switch on this.
      - `retryable` boolean, required: True when the same request may succeed later.
      - `next_action` 'retry_later' | 'fix_request' | 'start_over' | 'resync' | 'use_current_record' | 'none', required: What to do next.
      - `detail` string, required: This occurrence, in words.
    - `slug` string, nullable, required: Slug.
    - `name` string, nullable, required: Name.
    - `domain` string, nullable, required: Domain.
    - `record_url` string, nullable, required: URL.
    - `profile_url` string, nullable, required: URL.
    - `witnessed` object, nullable, required: Trooth's readings.
      - `standing` 'witnessed', nullable, required: witnessed
      - `last_witnessed_at` string, nullable, required: Time.
      - `first_witnessed_at` string, nullable, required: Time.
      - `unbroken_since` string, nullable, required: Time.
      - `checks_passed` integer, nullable, required: Count.
      - `checks_run` integer, nullable, required: Count.
    - `record` object, nullable, required: The version.
      - `version` integer, required: The record version.
      - `digest` string, required: A SHA-256 digest, 64 lowercase hex characters.
      - `recorded_at` string, required: When this version was recorded.
    - `pin` object, nullable, required: The pin and whether it still matches.
      - `sent` string, required: A SHA-256 digest, 64 lowercase hex characters.
      - `changed` boolean, required: True when the served version's digest differs from the pin, or the version cannot be confirmed: re-plan.
    - `facts` object, required: Whole days and counts from timestamps on the record; they rate nothing.
      - `days_since_last_witnessed` integer, nullable, required: Days.
      - `days_since_profile_updated` integer, nullable, required: Days.
      - `unbroken_readings` integer, nullable, required: Count.
      - `total_readings` integer, nullable, required: Count.
  - `how_to_read` string, required: How to read this answer.

## Other responses

- `400`: The body or a target cannot be used; errors[] points into the body.
- `413`: The body is larger than 16 KiB.
- `429`: Rate limited.

---

[API](https://skmtc.dev/trooth/apis/trooth-public-api.md) · [All operations](https://skmtc.dev/trooth/apis/trooth-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trooth/apis/trooth-public-api/revisions/e4d4e92641d9?raw)