Get Route Counts

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/transports/counts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "pending": 123,
  "active": 123,
  "error": 123
}

GET

transports

counts

Get Route Counts

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/transports/counts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "pending": 123,
  "active": 123,
  "error": 123
}

← Transport API Count your transport routes grouped by calculation status. This is the cheap call behind a “12 pending · 480 calculated · 3 failed” header — it returns three integers rather than the routes themselves, so you can poll it after an upload without paging through the data.

The three keys are always present. The query only returns statuses that have rows, but the response fills the missing ones with 0. A response of {"pending": 0, "active": 0, "error": 0} means “no routes match”, not “no data available” — you never have to check whether a key exists.

Request

Headers

string

required

UUID of the organization whose routes you are counting. Counting is scoped to this organization alone — routes belonging to child organizations of a holding are not included.Format: UUID

string

Your API key.

Query Parameters

string

Restrict the count to one direction. Omit it to count both.Available values: upstream, downstream

string

Restrict the count to the routes imported from one file. This is the parameter that makes the endpoint useful right after a bulk upload: it answers “how is my import doing”, not “how is the whole organization doing”.Format: UUIDTakes a single value. The list endpoint accepts several through a repeated file_id parameter; this one does not.

These counts are not the same population as the list or the totals, in two ways, and neither is visible in the response.No date filter. Unlike Get Totals, this endpoint counts every route that matches the two filters above, whatever its date. It cannot build a per-period counter — it will silently include every other period.Disabled routes are counted. The list and the totals both restrict themselves to enabled routes; this endpoint does not. A route that was logically deleted still adds to these numbers while contributing nothing to your emissions, so active here can exceed the record count you see anywhere else.

Response

integer

default:"0"

Routes queued for calculation and not yet processed.

integer

default:"0"

Routes calculated successfully. Note that this includes logically deleted routes, which do not feed your emissions totals — see the warning above.

integer

default:"0"

Routes whose calculation failed. A non-zero value here means part of your data is not in the totals — inspect them through the list endpoint with status=error.

Example

# Every route in the organization, by status
curl -X GET "https://api.dcycle.io/v1/transports/counts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

# Just the routes that came from one upload
curl -X GET "https://api.dcycle.io/v1/transports/counts?file_id=YOUR_FILE_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

import time

import requests

HEADERS = {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORGANIZATION_ID",
}


def wait_for_import(file_id, timeout=600, interval=10):
    """Poll until nothing is pending, then report what happened."""
    deadline = time.time() + timeout
    while time.time() < deadline:
        counts = requests.get(
            "https://api.dcycle.io/v1/transports/counts",
            headers=HEADERS,
            params={"file_id": file_id},
            timeout=30,
        ).json()

        if counts["pending"] == 0:
            return counts

        time.sleep(interval)

    raise TimeoutError(f"still pending after {timeout}s")


result = wait_for_import("YOUR_FILE_ID")
print(f"{result['active']} calculated, {result['error']} failed")

const params = new URLSearchParams({ file_id: fileId });
const response = await fetch(
  `https://api.dcycle.io/v1/transports/counts?${params}`,
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "x-organization-id": "YOUR_ORGANIZATION_ID",
    },
  },
);
const counts = await response.json();

const done = counts.pending === 0;
console.log(`${counts.active} calculated, ${counts.error} failed`);

Successful Response

Returns 200 OK.

{
  "pending": 12,
  "active": 480,
  "error": 3
}

Common Errors

422 Unprocessable Entity

Cause: x-organization-id is missing.

{
  "detail": [
    {
      "loc": ["header", "x-organization-id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Cause: transport_direction is not one of the two accepted values.

{
  "detail": [
    {
      "loc": ["query", "transport_direction"],
      "msg": "value is not a valid enumeration member; permitted: 'downstream', 'upstream'",
      "type": "type_error.enum",
      "ctx": {
        "enum_values": ["downstream", "upstream"]
      }
    }
  ]
}

Use Cases

Know when a bulk import has finished

After uploading transport routes, poll this endpoint with the file_id you uploaded until pending reaches 0. It is far cheaper than paging the list endpoint, and it gives you the failure count in the same response — so you learn both when the import finished and whether it worked.

Surface failures instead of losing them

A route in error is a route whose emissions are missing from your totals, and nothing in the totals themselves will tell you it is missing. Checking that error is 0 after each import turns a silent gap into a visible one.

List Transport Routes

The routes behind these counts, filterable by status

Get Totals

Aggregated CO2e and quantity, with date filters

Create Transport Route

Add the routes you will then be counting

Transport API

Everything the Transport API covers

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​422 Unprocessable Entity

​Use Cases

​Know when a bulk import has finished

​Surface failures instead of losing them

​Related Endpoints

List Transport Routes

Get Totals

Create Transport Route

Transport API

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

422 Unprocessable Entity

Use Cases

Know when a bulk import has finished

Surface failures instead of losing them

Related Endpoints