---
title: "Search the account's footprint history"
method: GET
path: "/v1/footprints/search"
tags: ["History"]
---

# Search the account's footprint history

`GET /v1/footprints/search`

## Request

- Base URL: `https://carbonguru.io`
- URL: `https://carbonguru.io/v1/footprints/search`
- Auth: HTTP bearer

## Query parameters

- `search` string
- `url` string
- `date_from` string, date
- `date_to` string, date
- `category` string
- `merchant` string
- `min_carbon` number
- `max_carbon` number
- `sort_by` 'date' | 'carbon_desc' | 'carbon_asc' | 'price'
- `limit` integer
- `offset` integer

## Response `200`

The account's matching footprints as Item resources, plus one global semantic match when `search` was given.

- FootprintSearch
  - `footprints` Item[], required
    - `carbonguru_id` string: The item's public handle on every CarbonGuru surface.
    - `session_id` string: The analysis session this item belongs to.
    - `item_number` integer: The item's position in its session, one-based.
    - `status` string
    - `source_type` string: How the item entered the platform: file, url, merchant_catalog, merchant_page.
    - `product_name` string, nullable
    - `activity` string, nullable: The activity line the analysis read.
    - `description` string, nullable
    - `category` string, nullable
    - `quantity` integer, nullable: Present when the source row carries a quantity of its own.
    - `price` number, nullable
    - `currency` string, nullable: ISO 4217.
    - `price_source` string, nullable
    - `price_date` string, nullable
    - `original_url` string, nullable: The page this item was read from.
    - `image_url` string, nullable
    - `merchant` string, nullable
    - `carbon_kg` number, nullable: The footprint, kg CO2e.
    - `pcf` number, nullable: The process-LCA footprint, where one applies.
    - `co2e_per_currency_unit` number, nullable: The emission factor applied: kg CO2e per unit of the item's currency.
    - `social_cost_usd` number, nullable: Social cost of carbon, USD (EPA 2023).
    - `offset_cost_usd` number, nullable
    - `offset_provider` string, nullable
    - `offset_product_id` string, nullable
    - `offset_quote_source` string, nullable
    - `offset_cache_age_s` integer, nullable: Age of this quote in seconds.
    - `offset_requested_qty_tons` number, nullable
    - `offset_orderable_qty_tons` number, nullable
    - `offset_provider_min_tons` number, nullable
    - `offset_display_cost_usd` number, nullable
    - `offset_orderable_cost_usd` number, nullable
    - `offset_defaults_applied` boolean, nullable
    - `offset_warnings` unknown[], nullable
      - unknown
    - `is_offset` boolean, nullable: The account has bought offsets for this footprint.
    - `is_removal` boolean, nullable: The account has bought removals for this footprint.
    - `offset_type` 'offset' | 'removal' | 'null', nullable
    - `offset_status` string, nullable
    - `offset_date` string, nullable
    - `is_acted_on` boolean, nullable
    - `acted_on_date` string, nullable
    - `lca_type` 'eio' | 'process' | 'null', nullable
    - `naics_code` string, nullable
    - `naics_title` string, nullable
    - `naics_vintage` string, nullable: 2017 or 2022. Null on rows written before the column existed.
    - `factor_naics_code_2017` string, nullable: The USEEIO factor code the footprint was computed from.
    - `sector_code` string, nullable: Open CEDA sector code, for a non-US country.
    - `sector_name` string, nullable
    - `emission_factor_source` string, nullable: USEEIO, Open CEDA, and so on.
    - `impact_factor_name` string, nullable
    - `impact_factor_id` string, nullable
    - `reference_product` string, nullable
    - `mapping_strategy` string, nullable: How the item was classified.
    - `justification` string, nullable: Why this classification was chosen.
    - `country_code` string, nullable: ISO 3-letter code the footprint was calculated for.
    - `country_detection_method` string, nullable: How the country was determined: declared, llm, meta, tld.
    - `price_adjusted` number, nullable: The price deflated to the factor's reference year.
    - `price_reference_year` integer, nullable
    - `price_adjustment_factor` number, nullable
    - `price_adjustment_applied` boolean, nullable
    - `manual_price` number, nullable
    - `manual_carbon_footprint` number, nullable
    - `manual_price_date` string, nullable
    - `manual_price_source` string, nullable
    - `original_price` number, nullable: The price a manual override replaced.
    - `original_carbon_footprint` number, nullable: The footprint a manual override replaced.
    - `correction_date` string, nullable
    - `correction_reason` string, nullable
    - `pcf_comparison` object, nullable: The full comparison against a reference product.
    - `pcf_comparison_product_name` string, nullable
    - `pcf_comparison_sector` string, nullable
    - `pcf_comparison_country` string, nullable
    - `pcf_comparison_pcf_value` number, nullable: The reference PCF, kg CO2e.
    - `pcf_comparison_percent_diff` number, nullable
    - `pcf_comparison_status` 'higher' | 'lower' | 'similar' | 'no_match' | 'null', nullable
    - `pcf_comparison_timestamp` string, nullable
    - `product_sku` string, nullable
    - `product_upc` string, nullable
    - `product_mpn` string, nullable
    - `product_model_number` string, nullable
    - `product_brand_part_number` string, nullable
    - `product_asin` string, nullable
    - `product_gtin` string, nullable
    - `product_item_number` string, nullable
    - `manufacturer_sku` string, nullable
    - `part_number` string, nullable
    - `product_identifiers` object, nullable
    - `order_number` string, nullable
    - `order_index` integer, nullable
    - `wc_product_url` string, nullable: The footprint page for this item.
    - `analyzed_at` string, nullable
  - `count` integer, required: Footprints on this page.
  - `total_available` integer, nullable: Footprints matching the filter across every page.
  - `global_semantic_match` object, nullable: One match from the global corpus, present when `search` was given. It names no session, account or identifier.
    - `found` boolean
    - `score` number, nullable
    - `product_name` string, nullable
    - `naics_code` string, nullable
    - `co2e_per_currency_unit` number, nullable
    - `carbon_kg` number, nullable

## Other responses

- `401`: No valid credential. Every authentication failure returns this one document.
- `403`: A missing scope, an exhausted analysis allowance, or an object that is not the caller's.
- `422`: The request's fields are wrong. errors[] names them.

---

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