Mortality

The mortality endpoints expose loss, mortality, and culling analytics for benchmarking farms in AquaCloud. All routes are read-only GET endpoints under the /v3/mortality prefix and share the v3 authentication model: supply an Authorization: Bearer <token> header and, for non-premium farmer tiers, add the issued x-client-secret header. Empty result sets return 204 No Content.

Common query parameters

Name	Type	Default	Details
from_date	date	Varies by route (4–12 weeks lookback)	Flexible parsing: accepts ISO (2024-03-31), 31/03/2024, named months (mai 2024), week notations (week 12 2024), quarters (Q1 2024), and relative values (today, yesterday). Partial inputs resolve to the start of the period.
to_date	date	Today	Same parsing rules as from_date; partial values resolve to the end of the period.
areas	list of strings	All areas	Comma-separated AquaCloud area names (Norwegian or English) or IDs. Use % to explicitly select all areas.
generations	list of strings	All generations	Comma-separated generation codes (e.g. H2023) or localized names (e.g. Høst 2023).
weight_range_start	integer	1 (most endpoints)	Minimum individual fish weight in grams. /mortality/size/month accepts 0.
weight_range_end	integer	15000	Maximum individual fish weight in grams.
exclude_self	boolean	false	Excludes the authenticated farmer when true.
offset	integer ≥ 0	0	Number of rows to skip for pagination.
limit	integer (1–1000)	1000	Maximum rows returned. Services request limit + 1 rows to populate pagination.has_more.

Endpoint-specific parameters

• loss_type: Accepts loss (default, includes mortality + culling) or mortality to focus on unplanned deaths. Used by /mortality/categories/rank/week.
• number_of_categories: Max categories ranked per week (default 10).
• period: Rolling window length in weeks for trend calculations (1–52).
• period_grouping: One of month, quarterly, tertial, year for /mortality/categories/rate.
• group_by: area, generation, or area_and_generation for size aggregations.
• weight_bucket: Bucket width in grams (100–5000) for /mortality/size/categories.

Response envelope

Every endpoint returns:

• data: List of resource records described below.
• pagination: Includes offset, limit, and has_more where pagination applies. /mortality/size/categories always reports has_more: false.
• metadata: Contains the API version, optional request_id, and the farmer group key when exclude_self=true.

Endpoints

GET /v3/mortality/areas/week

Returns weekly loss, mortality, and culling rates by AquaCloud area.

Field	Type	Description
loss_rate_week	string (ISO week date)	Monday of the ISO week.
aquacloud_area_name	string	Human-readable area name.
production_area_ids	array of integers	Production area identifiers bundled into the area.
site_count	integer	Benchmark site count contributing to the row.
mortality_rate/culling_rate/loss_rate	number	Benchmark rates for the selected filters.
farmer_site_count	integer	Authenticated farmer’s site count in the row.
farmer_mortality_rate/farmer_culling_rate/farmer_loss_rate	number	Farmer-specific rates for comparison.

Default window: from_date is 12 weeks prior to today.

GET /v3/mortality/categories/rank/week

Tracks the top loss categories week-by-week, including optional rolling windows.

Field	Type	Description
rank	integer	Rank of the category within the week.
loss_week	string	Week (ISO date).
loss_category_code / loss_category_name	string	Category identifiers.
loss_rate, mortality_rate	number	Benchmark rates for the category.
loss_rate_change, mortality_rate_change	number	Week-over-week change.
trending_loss_last_n_weeks, trending_mortality_last_n_weeks	number	Rolling trend using the supplied period.

Defaults: from_date 4 weeks back, number_of_categories 10, loss_type=loss.

GET /v3/mortality/region/rolling-12-month

Internal (not listed in the OpenAPI schema) rolling 12-month benchmark by production region.

Key fields include region name (production_region_name), placement (site_placement), monthly loss date (loss_rate_month), weighted and average loss/mortality/culling rates with 3/6/12-month cumulative variants, and site_count. Use when you need the extended FDIR-style region view.

GET /v3/mortality/categories/distribution

Shows the share of total losses by category over time.

Field	Type	Description
loss_month	string	Month label.
loss_category_code	string	Category identifier.
loss_count / loss_biomass_kg	number	Benchmark counts and biomass.
loss_rate_count / loss_rate_biomass	number	Share of losses attributed to the category.
farmer_loss_*	number	Farmer-equivalent metrics (count, biomass_kg, rate variants).
loss_rate_*_of_inventory	number	Category proportion relative to total inventory.
total_loss_rate, farmer_total_loss_rate	number	Overall loss rate for the time bucket.
category_name, category_short_name, category_code_level_1/2	string	Category descriptors.

GET /v3/mortality/categories/rate

Aggregates loss categories over configurable periods (month, quarterly, tertial, year).

Field	Type	Description
period	string	Aggregation window label.
loss_category_code	string	Category identifier.
loss_count, mortality_count, culling_count	integer	Benchmark event counts.
*_avg_weight_gram	number	Average weight for loss/mortality/culling events.
farmer_*	number	Farmer-specific counts and averages.
loss_rate, mortality_rate, culling_rate	number	Benchmark rates per category.
farmer_loss_rate, farmer_mortality_rate, farmer_culling_rate	number	Farmer comparison rates.
category_name, category_short_name, category_level_1_name	string	Human-friendly labels.

GET /v3/mortality/categories/rank

Ranks loss categories across the selected period range.

Field	Type	Description
loss_category_code	string	Category identifier.
period_start, period_end	string	Covered period boundaries.
*_count, *_biomass_kg, *_avg_weight_gram	number	Benchmark totals for mortality, culling, and loss.
*_rate_of_total_in_period	number	Category share of total events/biomass.
farmer_*	number	Same metrics calculated for the authenticated farmer.
loss_category_name	string	Category label.

GET /v3/mortality/generations/rate

Benchmark loss, mortality, and culling rates by generation across areas.

Field	Type	Description
loss_rate_month	string	Month end of the measurement.
generation	string	Generation code.
generation_month_number	integer	Months since transfer to sea (benchmark).
farmer_generation_month_number	integer	Same metric for the farmer (if available).
aquacloud_area_name / production_area_ids	string / array	Geographic context.
loss_rate, mortality_rate, culling_rate	number	Benchmark rates.
cumulative_*	number	Rolling cumulative rates (benchmark and farmer).
farmer_*	number	Farmer-specific rates.

GET /v3/mortality/size

Provides loss share by size buckets.

Field	Type	Description
weight_group_gram	integer	Bucket midpoint.
group_by	string	Dimension used: area, generation, or area_and_generation.
production_area_ids	array	Included production areas (when grouped by area).
rate_of_total_loss	number	Benchmark share of total loss in the bucket.
farmer_rate_of_loss	number	Farmer share for the same bucket.

GET /v3/mortality/size/month

Tracks average loss weights by month while retaining the chosen grouping.

Field	Type	Description
month	string	ISO month label.
group_by	string	Grouping in effect.
loss_avg_weight_gram	integer	Benchmark average loss weight.
farmer_loss_avg_weight_gram	integer	Farmer average.

weight_range_start can be 0 for this route.

GET /v3/mortality/areas/month

Monthly loss, mortality, and culling metrics per area with cumulative benchmarks, farmer comparisons, and FDIR references.

Headline fields: area (aquacloud_area_name, production_area_ids), month, site_count, benchmark rates (mortality_rate, culling_rate, loss_rate) and their 3/6/12-month cumulative counterparts, farmer equivalents (farmer_*) including cumulative site averages, plus FDIR baselines (fdir_*). Use this dataset for dashboards that need month-level benchmarking with farmer, area, and national reference values in a single payload.

GET /v3/mortality/size/categories

Breaks down loss categories per weight bucket.

Field	Type	Description
category_code_level_1	string	Top-level category code.
category_name	string	Category label.
weight_group	integer	Bucket midpoint in grams.
rate, mortality_rate, culling_rate	number	Benchmark shares for all loss types.
farmer_rate, farmer_mortality_rate, farmer_culling_rate	number	Farmer benchmarks.

Pagination metadata is static (has_more: false) because the dataset is returned as a single page.

Example request

GET /v3/mortality/categories/rate?areas=Nord&from_date=2024-01-01&to_date=2024-03-31&period_grouping=quarterly&exclude_self=true HTTP/1.1
Host: api.aquacloud.io
Authorization: Bearer <token>
x-client-secret: <client-secret>

Successful responses will include the aggregated category rows in data, pagination information (if more rows remain), and a metadata.request_id for support tracing.