GraphQL API

One query.
Full audit trail.

Fetch assets, products, calculations, emission factors and their source registry in a single round-trip. Built for CSRD auditors, BI dashboards, and LLM integrations that need the whole graph.

POST https://carbontrace.cloud/api/v1/graphql

Graph-native

Asset → product → calculation → factor → registry walked in one query, not five.

Frozen source references

Calculation cards preserve inputs and assumptions. A linked original factor is returned only when an unambiguous frozen ID is available; missing provenance returns null.

Scenario mutations

Simulate equal-service refurbishment or next-quarter power-off. Inventory stays unchanged; execution is audit-logged.

Quickstart

Use any API key from your settings page. Test keys (ct_test_*) return sandbox data so you can develop without hitting live data.

curl -X POST https://carbontrace.cloud/api/v1/graphql \
  -H "Authorization: Bearer ct_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query OrgOverview { organization { id name plan asset_count total_kg_co2e } }"
  }'

Example queries

Use these supported queries to start your integration. API access and custom-query availability depend on your plan.

Methodology walkthrough

Read asset, calculation and available frozen grid-factor references. A registry link does not establish independent assurance.

query MethodologyAudit($assetId: ID!) {
  asset(id: $assetId) {
    id
    brand
    mpn
    total_kg_co2e
    production_kg
    use_phase_kg

    active_calculation {
      id
      created_at
      total_kg_co2e
      emission_factor(type: GRID) {
        value
        unit
        source
        source_version
        source_url
        source_license
        registry {
          display_name
          current_version
          next_check_after
        }
      }
    }
  }
}

Asset detail

Fetch an asset with its linked product and optional global catalog match (PCF data if available).

query AssetDetail($id: ID!) {
  asset(id: $id) {
    id
    brand
    mpn
    serial_number
    status
    purchase_date
    country
    total_kg_co2e
    product {
      id
      brand
      mpn
      name
      category
    }
  }
}

Organization overview

Current asset lifecycle totals; not automatically a reporting-period emissions inventory.

query OrgOverview {
  organization {
    id
    name
    plan
    asset_count
    total_kg_co2e
  }
}

Factor by region + date

Reference lookup by region and date; it does not prove a factor was used in a saved calculation.

query FactorLookup($region: String!, $atDate: DateTime) {
  factorByRegion(type: GRID, regionCode: $region, atDate: $atDate) {
    value
    unit
    source
    source_version
    valid_from
    valid_to
  }
}

Simulate refurbish (mutation)

Compare one new purchase with refurbishment for the same next quarter. Original production is sunk in the scenario; common end-of-life is excluded.

mutation Refurbish($ids: [ID!]!) {
  simulateRefurbish(assetIds: $ids) {
    current_quarterly_co2e
    scenario_quarterly_co2e
    delta_kg_co2e
    delta_percentage
    affected_assets_count
  }
}

Limits and gotchas

GraphQL shares rate limits with the REST API. Check your current plan and the response headers; handle rate-limit errors before retrying.
Plans with API access may be restricted to approved queries. Custom queries require the GraphQL custom-query feature. The pricing comparison lists current availability.
Asset queries return max 100 rows per page. Use the after cursor for pagination.
Scenario mutations cap at 500 assets per call. Larger portfolios need to be batched client-side.
Read methodology_card, boundary and assumptions where accessible. Engine v4 uses gross modelled EoL processing, separate recovery scenarios and non-statistical sensitivity. Negative scenario delta means lower estimated emissions, not an inventory deduction. Adding fields to the five templates requires an approved query or an ad-hoc plan.

Full reference

The REST API is still the primary surface. GraphQL is for graph-shaped reads and what-if scenarios.

REST API docs New to GraphQL?

One query.Full audit trail.