---
title: "Compare how much ammunition each firearm carries per kilogram"
method: GET
path: "/v1/firearms/ammo-load"
tags: ["Firearm Analysis"]
---

# Compare how much ammunition each firearm carries per kilogram

`GET /v1/firearms/ammo-load`

## Request

- Base URL: `https://api.gunspec.io`
- URL: `https://api.gunspec.io/v1/firearms/ammo-load`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns, for each of up to 5 firearms, its ammunition as a weight, in two kinds of figure that are never mixed.

**Derived** from the catalogue: a full magazine is the firearm's loaded weight less its empty weight, as load carriage takes it, and from it and the magazine's capacity come the rounds carried per kilogram of full magazines and how many full magazines and rounds fit `budget_kg`. Only a detachable magazine comes out whole, so a firearm with a fixed magazine, a tube or a clip is answered without these, with a warning.

**Estimated** by the fitted cartridge-mass model: a basic load of `rounds` rounds (default `magazines` times the capacity) and of `magazines` full magazines, from the bullet (the load named by `ammo_id`, or the cartridge's typical bullet) and the case's dimensions. The model was fitted to four cartridges whose mass a source states and misses none by more than 8.5%; every estimate carries that error as a range, and is labelled `estimated`. An estimate is never catalogue data.

The model also checks each derived magazine: one lighter than its rounds alone are estimated to weigh, allowing the model's whole error, means one of the record's two weights is wrong, and the answer says so beside the figures derived from it.

**Requires Builder tier or higher.**

## Query parameters

- `ids` string, required
- `ammo_id` string
- `budget_kg` number
- `magazines` integer
- `rounds` integer

## Headers

- `If-None-Match` string

## Response `200`

Compare how much ammunition each firearm carries per kilogram

- object
  - `success` boolean, required: Always true on a successful response. Every error carries `false` and an `error` object instead.
  - `data` object, required: The response payload.
    - `method` object: The method behind every figure in the answer.
      - `id` string: The method the figures were computed with.
      - `name` string: The method by name.
      - `equation` string: The arithmetic and the model as written, with units, so the figures can be reproduced.
      - `maxErrorPct` number: The model's largest error on its reference cartridges, in percent: the range every estimate carries.
      - `fittedEnvelopeCm3` number[]: The smallest and largest case envelope the model was fitted on, in cm³.
      - `references` object[]: The cartridges the model was fitted to.
        - `name` string: The cartridge.
        - `load` string: The load whose mass is stated.
        - `roundG` number: The loaded round's mass as its source states it, in grams.
        - `source` string: Where the mass is stated.
    - `load` object: The load every firearm was answered for.
      - `budgetKg` number: The weight budget in kg.
      - `magazines` integer: Full magazines in the estimated basic load.
      - `rounds` integer, nullable: Rounds in the estimated basic load, as given. Null when each firearm's came from its capacity.
      - `ammoId` string, nullable: The load named, if any.
      - `defaulted` string[]: The query parameters not sent, answered from their defaults.
    - `results` object[]: One result per firearm, in the order their ids were given.
      - `firearm` object: The firearm this result is for.
        - `id` string: Firearm slug.
        - `name` string: Firearm name.
        - `magazineType` string, nullable: How the firearm feeds, as the catalogue records it.
        - `magazineCapacity` integer, nullable: Rounds in a standard magazine.
      - `cartridge` object, nullable: The cartridge the estimate is for. Null when the firearm records none.
        - `caliberId` string: The cartridge estimated.
        - `bulletG` number, nullable: The bullet mass the estimate uses, in grams.
        - `bulletSource` 'ammunition' | 'caliber' | 'null', nullable: `ammunition` for the named load's bullet, `caliber` for the cartridge's typical bullet.
        - `ammunitionId` string, nullable: The load whose bullet is used, if one.
        - `envelopeCm3` number, nullable: The case envelope in cm³: π/4 × base diameter² × case length.
      - `magazine` object, nullable: A full magazine, derived. Null when the feed is not detachable or a weight or the capacity is not recorded.
        - `loadedMagazineG` number: One full magazine in grams: loaded weight less empty weight.
        - `capacity` integer: Rounds in it.
        - `roundsPerKg` number: Rounds carried per kilogram of full magazines.
        - `source` 'derived': Always `derived`: arithmetic on two figures the record states.
        - `check` object, nullable: The derived magazine held against the cartridge-mass model. Null when no round mass could be estimated.
          - `verdict` 'plausible' | 'lighter-than-rounds' | 'below-band' | 'above-band': How the derived magazine sits against the model: `lighter-than-rounds` means one of the two weights is wrong.
          - `roundsG` object: What the rounds alone weigh, estimated.
            - `expected` number: What the rounds alone weigh: the model's expected value.
            - `low` number: The expected value less the model's largest reference error.
            - `high` number: The expected value plus it.
          - `bandG` object: The model's band for a full magazine: the rounds and an empty magazine.
            - `low` number: Lightest full magazine the model allows, in grams.
            - `high` number: Heaviest.
          - `source` 'estimated': Always `estimated`.
      - `budget` object, nullable: What `budget_kg` of full magazines holds. Null when no full magazine was derived.
        - `magazines` integer: Full magazines the budget holds.
        - `rounds` integer: Rounds in them.
        - `massG` number: What they weigh, in grams.
        - `leftoverG` number: What is left of the budget, in grams.
        - `source` 'derived': Always `derived`.
      - `basicLoad` object, nullable: A basic load's mass by the cartridge-mass model. Null when the cartridge lacks the figures the model needs.
        - `rounds` integer: Rounds estimated.
        - `roundG` object: One round, estimated.
          - `expected` number: One round: the model's expected value.
          - `low` number: The expected value less the model's largest reference error.
          - `high` number: The expected value plus it.
        - `roundsG` object: The rounds together, estimated.
          - `expected` number: The rounds together: the model's expected value.
          - `low` number: The expected value less the model's largest reference error.
          - `high` number: The expected value plus it.
        - `magazines` integer: Full magazines estimated.
        - `magazinesG` object, nullable: The full magazines, estimated: the rounds and the model's band for an empty magazine, so wider than the rounds alone. Null without a detachable magazine and a capacity.
          - `expected` number: The full magazines, rounds and magazine bodies: the model's expected value.
          - `low` number: The expected value less the model's largest reference error.
          - `high` number: The expected value plus it.
        - `source` 'estimated': Always `estimated`: the fitted model, never catalogue data.
      - `delta` object, nullable: Against the option that carries the most rounds per kilogram, leaving out any magazine the model finds lighter than its rounds. Null on that option, on a lone firearm, and where no magazine was derived.
        - `roundsPerKg` number: Rounds per kilogram against the densest option (negative: fewer).
        - `budgetRounds` integer: Rounds in the budget against it.
      - `warnings` string[]: Why a figure is missing, or why a derived one is doubtful.
      - `error` string, nullable: Why nothing could be computed for this firearm. Null when anything was.

## Other responses

- `304`: Your copy is current. No body is sent, and this response does not count toward the daily request allowance.
- `400`: Validation error
- `401`: Missing or invalid API key
- `403`: The credential is valid and the caller is not permitted. Three causes, none of which reissuing a key changes: the plan is below the endpoint's tier, the account is suspended, or the key is not attached to the thing being acted on, meaning a user account for `/v1/me` or a shop for `/v1/vendor`. Distinct from 401, which means the credential is missing, malformed or expired and a new one can work.
- `404`: Resource not found
- `429`: A limit was reached. `RATE_LIMITED` is the per-minute limit: wait `Retry-After` seconds (a minute) and retry. `DAILY_CAP_EXCEEDED` is the plan's daily limit, per key: nothing will be served until the counters return to zero at midnight UTC. `MONTHLY_CAP_EXCEEDED` is the plan's monthly allowance, for the whole account: nothing will be served until midnight UTC on the first of next month, or until the plan changes. For both, `Retry-After` is the seconds until then and `error.resetsAt` says when as an instant. Calls made after a refusal are refused too and do not spend the month, and a free key that keeps calling is paused, so stop at the first one and resume at the reset.
- `500`: Internal server error

---

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