Mortality (v2)

The legacy mortality endpoints provide high-level benchmarks and category catalogues used by earlier AquaCloud dashboards. All routes require authentication. Endpoints that support the exclude_self flag only return a result when the token represents a farmer group.

Category catalogue endpoints

GET /v2/mortality/categories/codelist

Returns the full mortality category catalogue with optional pagination.

Query parameters

Name	Type	Default	Notes
offset	integer	0	Starting index within the catalogue.
limit	integer	500	Number of rows to return.

Response fields (data[])

Field	Type	Description
level_1_code, level_1_name	string	Top-level category code/name.
level_2_code, level_2_name	string	Second-level grouping.
level_3_code	string	Third-level code.
category_name, category_name_short	string	Norwegian labels.
category_name_eng, category_name_short_eng	string	English labels.
for_daily_registration	boolean	Indicates whether the category supports daily reporting.
reporting_obligation	any	Raw value indicating legal reporting requirements.
placement	object	Availability flags per placement (sea, land).
cause	object	Availability flags for death causes (death, killed, downgrade).
value_chain	object	Flags for value-chain stages (roe, postsmolt, freshwater, etc.).
species	object	Species booleans (salmon, cleanerfish, rainbow_trout).
last_modified	string	Last updated timestamp (ISO).

metadata contains the response timestamp (time) and the most recent last_modified across the returned slice.

GET /v2/mortality/categories/changelog

Provides recorded changes to mortality categories.

data[] entries include:

Field	Description
date	Change timestamp.
from_code / from_name	Category that was changed.
to_code / to_name	Replacement category (when applicable).
description	Human-readable change note.
changed_by	Origin of the change (e.g. authority or internal source).

GET /v2/mortality/categories/level-1

GET /v2/mortality/categories/level-2

Return simplified lists of level 1 or level 2 codes with their names. Use these for quick drop-down population when you do not need the full codelist metadata.

Benchmark endpoints

GET /v2/mortality/mortality-rate-by-region

Produces monthly mortality benchmarks for each region.

Query parameters

Name	Type	Default	Notes
exclude_self	boolean	false	When true, removes the authenticated farmer’s sites before calculating benchmarks. Requires a farmer token.

Response structure

data[] entries contain:

Field	Type	Description
year, month	integers	Reporting period.
region	string	Region identifier.
number_of_sites	integer	Sites included after filters.
mortality_rate	object	Rates (1_m, 3_m, 6_m, 12_m, year).
vi_mortality_rate	object	Mortality rates weighted by biomass (same keys as above).
mortality_code_rate	object	Rates for top-level mortality codes (A–F).
highest_10_percent_avg_rate / lowest_10_percent_avg_rate	object	Benchmark extremes (nullable).
highest_10_percent_avg_vi_rate / lowest_10_percent_avg_vi_rate	object	Biomass-weighted extremes (nullable).

metadata.time captures the response timestamp and metadata.request.exclude_self echoes the supplied filter.

GET /v2/mortality/mortality-rate-by-country

Matches the regional endpoint but aggregates nationwide. The response fields are identical except that the region column is omitted.

GET /v2/mortality/categories/top-by-region

Lists the dominant mortality categories per region and month. Supports the same exclude_self parameter as the rate endpoints.

data[] fields:

Field	Description
year, month	Reporting period.
region	Region label.
mortality_code	Category code.
category_rate	Share of loss attributed to the category (0–1).

GET /v2/mortality/categories/top-by-country

Identical to the regional version but aggregated at the country level (no region field).

Both “top” endpoints return metadata.time and echo the exclude_self flag in metadata.request.

Example requests

# Region benchmark excluding own farmer
curl -X GET "https://api.aquacloud.ai/v2/mortality/mortality-rate-by-region?exclude_self=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-secret: $CLIENT_SECRET"

# Fetch the mortality codelist catalogue
curl -X GET "https://api.aquacloud.ai/v2/mortality/categories/codelist?limit=200" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-secret: $CLIENT_SECRET"