Treatment

Treatment endpoints under /v3/treatment surface lice mitigation and health-intervention activity. They provide multiple aggregation levels (area, category, site, generation, and weight buckets) to help correlate treatment pressure with losses or environmental conditions. All routes are read-only GET endpoints. Authenticate with Authorization: Bearer <token> and add x-client-secret for non-premium farmer tiers.

Unlike other resource families, treatment filters expect ISO YYYY-MM-DD values for start_date/end_date. Supplying other formats will return a 400 error.

Common filters

Name	Applies to	Description
start_date / end_date	All routes	Inclusive date range; use ISO YYYY-MM-DD. When omitted the service returns the full available window.
areas	All routes	Comma-separated production area IDs. Use % (default) to include all.
species_code	Summary, detail, site	Filter on species code (e.g. S for salmon).
treatment_category	Detail, site, generation, size	Category filter (Bath, Medicinal, Mechanical, Combination, etc.).
treatment_target	Detail, site, generation, size	Target filter (Lice, Bacteria, Parasites, Health, etc.).
min_treatments	Summary	Minimum total treatments before a row is returned.
min_category_treatments, min_category_share	Detail	Thresholds for including category rows.
requires_handling, is_antibiotic	Site	Boolean flags for handling-heavy or antibiotic treatments.
owner_id, site_id	Site, generation, size	Narrow to specific owners or sites.
generation	Generation, size	Comma-separated generation codes.
group_by_area	Generation	When true, aggregates by production area instead of individual sites.
min_weight_gram, max_weight_gram, exclude_totals	Size	Control weight-bucket range and whether TOTAL rows are removed.

All list endpoints support offset/limit pagination (default 0/100) and return pagination.has_more when additional pages are available.

Endpoints

GET /v3/treatment/summary-by-area-and-week

Aggregated treatment volume per production area and ISO week with contextual signals.

Field	Type	Description
production_area_id / production_area_name	string	Area identifiers.
species_code	string	Species filter applied.
week_start / year_week	date / string	Week metadata (week_start is the Monday).
total_treatments	integer	Total treatments in the week.
sites_treated / owners_involved	integer	Activity coverage.
days_with_treatments	integer	Number of active treatment days.
antibiotic_treatments, mechanical_treatments, bath_treatments, thermal_treatments	integer	Category-specific totals.
lice_treatments, parasite_treatments, bacteria_treatments	integer	Target-specific totals.
treatments_4_week_rolling	number	Four-week rolling average.
week_over_week_change, week_over_week_pct_change, month_over_month_change, year_over_year_change	number	Change metrics.
trend_status, treatment_intensity	string	Qualitative signals (e.g. increasing, high).
significant_increase, significant_decrease	boolean	Statistical change flags.
has_antibiotic_use, multiple_treatment_types	boolean	Additional context flags.

GET /v3/treatment/detail-by-category-and-week

Breaks the summary down by treatment category and target, retaining the same week granularity.

Field	Type	Description
treatment_category / treatment_target	string	Category and target combination.
category_treatment_count	integer	Treatments for the category in the week.
category_sites_treated / category_owners_involved	integer	Coverage metrics for the category.
category_handling_treatments, category_antibiotic_treatments	integer	Handling/antibiotic totals.
category_treatments_4_week_rolling, category_week_over_week_pct_change	number	Rolling statistics.
area_total_treatments, area_total_handling_treatments, area_total_antibiotic_treatments	number	Area totals for context.
category_share_of_area_pct	number	Share of the area's treatments accounted for by the category.
category_trend_status, category_treatment_intensity	string	Qualitative indicators.
category_significant_increase, category_significant_decrease	boolean	Significant change flags.
is_only_category_this_week, is_majority_category_this_week	boolean	Category dominance flags.

GET /v3/treatment/by-site

Returns raw treatment records per site and day for compliance and auditing.

Field	Type	Description
owner_id, site_id	string	Farmer/site identifiers.
placement_type	string	Site placement (offshore/onshore).
treatment_date, treatment_week, treatment_month	date	Daily, weekly, and monthly anchors.
treatment_category, treatment_target, treatment_subtype	string	Detailed treatment classification.
requires_handling, is_antibiotic	boolean	Risk indicators.
system_source, data_source	string	Data provenance.
treatment_site_scope	string	Scope of the treatment (full/partial).
number_of_units_treated	integer	Units treated when reported.
treatment_count	integer	Count of treatment events captured.

GET /v3/treatment/by-generation

Shows cohort-level treatment progression, optionally aggregated by production area when group_by_area=true.

Field	Type	Description
owner_id, cohort_id, site_id	string	Identifiers for the cohort and site.
site_placement	string	Offshore/onshore placement.
production_area_id, production_region_name	integer / string	Location context (may be null when aggregating).
generation	string	Generation code (e.g. H2019).
treatment_week, generation_start_week	date	Week of treatment and cohort start.
treatment_category, treatment_target, category_target_combination	string	Treatment classification.
weeks_from_generation_start	integer	Week offset from generation start.
absolute_treatment_count, days_with_treatments	integer	Weekly treatment totals.
absolute_antibiotic_treatment_count	integer	Antibiotic count for the week.
cumulative_treatment_count, cumulative_antibiotic_count	integer	Running totals across the generation.

GET /v3/treatment/by-size

Aggregates treatment activity by weight bucket to highlight intensity at different fish sizes.

Field	Type	Description
owner_id, site_id	string	Farmer/site identifiers.
production_area_id, production_region_name	integer / string	Location context (nullable).
generation	string	Generation code.
treatment_week	date	Week anchor.
weight_group_gram	number	Weight bucket midpoint in grams.
avg_weight_gram	number	Reported average fish weight.
treatment_category, treatment_target, category_target_combination	string	Treatment classification.
treatment_count, days_with_treatments, antibiotic_treatment_count	number	Activity metrics rounded to four decimals.

Example requests

Paginated summary query:

GET /v3/treatment/summary-by-area-and-week?start_date=2023-11-01&end_date=2024-01-31&areas=4,5&limit=200 HTTP/1.1
Host: api.aquacloud.ai
Authorization: Bearer <token>
x-client-secret: <client-secret>

Site-level drill-down scoped to antibiotic events:

GET /v3/treatment/by-site?start_date=2024-01-01&end_date=2024-03-31&is_antibiotic=true&limit=100 HTTP/1.1
Host: api.aquacloud.ai
Authorization: Bearer <token>
x-client-secret: <client-secret>

Both routes return treatment records in data with pagination to help iterate through historical periods.