High-volume API usage

This guide is for teams sending high volumes of requests to the Climatiq API: automated pipelines, bulk emissions calculations, or integrations using the Mapping Agent at scale. It covers how the API handles concurrency, how to design integrations that stay within limits, and how to use batch endpoints efficiently.

Concurrency limits

Climatiq allows 10 in-flight requests per user at any one time. This limit applies across all endpoints.

When you exceed 10 concurrent requests, additional requests are queued rather than rejected. You will not receive a 429 error. Queued requests are processed as capacity frees up, but sustained throughput above the limit means growing response times as the queue builds.

In practice, the first 10 requests begin processing immediately; anything beyond that queues until a slot opens. Sending 50 requests at once is no faster than sending 10, so keeping your integration at or below the limit gives you the best possible throughput.

Designing for parallelism

To stay within the 10-request limit, control the number of in-flight requests explicitly in your integration. The standard approach is a semaphore (or thread pool) capped at 10, which allows new requests to be dispatched as previous ones complete. Most HTTP client libraries and concurrency frameworks support limiting concurrent requests directly.

If you mix batch operations with interactive user-facing requests, consider capping batch concurrency at 8 or similar to keep a few slots free for users who shouldn’t have to wait in the queue.

Batch endpoints for throughput

For operations that process many items of the same type, the batch endpoints are the most efficient approach.

A single batch request can contain up to 100 operations and counts as a single in-flight request against your concurrency limit. The efficiency gain is fewer HTTP round trips: 100 items sent as one batch request completes faster than 100 individual requests, even though the operations are processed in sequence internally. Each operation in a batch still counts as one API call against your plan quota - batching does not reduce consumption.

Key behaviors to be aware of:

• Consumption: each item that is successfully processed counts as one API call towards your plan quota. Failed items are not billed.
• Partial failure: the batch endpoint returns HTTP 200 even if some operations fail. You must inspect each item in the response individually to detect errors.

Supported endpoints include Basic Estimate, Energy, and Procurement. See the batch endpoints reference for the full list.

Mapping Agent at scale

The Mapping Agent has higher per-request latency than most other endpoints, as each request involves model inference. The Mapping Agent does not have a batch endpoint, so each item requires its own request.

The same 10 concurrent request limit applies. For high-volume Mapping Agent usage, use the semaphore pattern described above to keep in-flight requests at or below 10. Sending hundreds of requests simultaneously without concurrency control will result in a growing queue and degraded response times for all requests on that API key.

For very high-volume datasets where throughput matters more than match precision, set effort=low in your requests. This reduces per-request latency at the cost of match accuracy. The default effort=high is recommended for most use cases.

Test with a subset first

Before running a large dataset, always validate your integration against a small representative sample. This lets you catch errors in your input format, review the quality of results, and estimate your total API consumption before committing to a full run.

A sample of 50 to 100 items is usually enough to surface input formatting issues, unexpected results, or mismatched activity types. Once you are confident in the output quality, scale up to the full dataset.

Supporting resources