N87 Beta · Scope M

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.

Audit-grade

Every calculation links back to the factor that was active at calc time, with full source provenance.

Scenario mutations

Simulate refurbish or retirement without touching the database. Safe on locked and certified assets.

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 { organization { name plan asset_count total_kg_co2e } }"
  }'

Example queries

Every example below is pre-approved on the free and pro plans (persisted query whitelist). Business and enterprise plans can submit custom queries.

Methodology walkthrough

One call for the full audit trail. Asset → calculation → grid factor → source registry. Built for CSRD auditors.

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
      catalogMatch {
        has_pcf
        pcf_total_kg
        pcf_standard
        pcf_year
      }
    }
  }
}

Organization overview

Current org summary with asset count and total booked CO₂e.

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

Factor by region + date

Look up the grid factor that was active for a region on a specific date. Same primitive used internally by the methodology walkthrough.

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)

What-if scenario: extend useful life instead of replacing. Pure compute — nothing gets written to the database.

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

Limits and gotchas

Rate limits are shared with the REST API — same per-minute and per-day quotas per plan. Free: 25/day, Pro: 1000/day, Business: 10000/day, Enterprise: 100000/day.
Free and pro plans can only execute whitelisted queries (the 5 above). Business and enterprise may submit any query.
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.

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.