# API overview

The Tracenable API provides programmatic access to our comprehensive corporate datasets. Built on REST principles, it enables you to integrate verified company data directly into your applications, research models, and internal workflows.

{% hint style="info" %}
The Tracenable API is currently in **Beta**. Access is limited to **Company** (Search/List) and **GHG Emissions** endpoints. We are actively expanding the API and will release additional datasets and endpoints in the coming weeks.\
\
We welcome your feedback to help shape the product. Please send any comments, suggestions, or feature requests to <support@tracenable.com>.
{% endhint %}

You can use the API to identify companies and retrieve their full datasets for specific reporting periods.

### Base URL

All API requests should be made to the following base URL:

```http
https://tracenable.com/api/v1
```

### Authentication

The API uses Bearer Authentication. To access the API, you must include your API key in the `Authorization` header of each request.

To generate an API key, please visit [the API key page](https://staging.tracenable.com/settings/api-key).&#x20;

#### Header Format:

```http
Authorization: Bearer <YOUR_API_KEY>
```

{% hint style="warning" %}
Your API keys carry the same privileges as your user account. Keep them secure and never expose them in client-side code
{% endhint %}

#### Test Mode

You can explore the API and test your integration without consuming any credits by using our dedicated test token. Requests made with this token return mock data and are free of charge.

```http
Authorization: Bearer sk_test_tracenable
```

### Core Concepts

The API is designed around two primary actions: identifying companies and retrieving their data.

1. **Company Identification**: Use the Search or List endpoints to resolve a company's unique identifiers (such as `company_id`, ISIN, or LEI) using their name or ticker symbol.
2. **Data Retrieval**: Once you have identified a company, you can retrieve its full dataset for a specific reporting period (year). Unlike traditional APIs that might require fetching individual metrics, a single call to our endpoints retrieves all available data points for that company and year.

### Response Codes & Data Availability

* **200 OK**: The request was successful, and data was returned.
* **204 No Content**: The company and reporting period exist, but the company did not publish any data for that specific year (e.g., they released a report but it did not contain the requested data).
* **404 Not Found**: The company or reporting period could not be found, or the relevant documents have not yet been processed by our platform.

### Pricing & Credits

The Tracenable API operates on a usage-based credit system.

* **Pay-As-You-Go**: You only pay for the data you successfully retrieve.
* **Cached Data**: Once you have purchased data for a specific company and year, subsequent requests for that same data (returning a `200 OK`) are charged at a significantly reduced "cached" rate.
* **No Expiration**: Unused credits never expire.

You can monitor the cost of each call via the custom response headers included in every successful response:

* `x-credit-cost`: The cost of the specific request.
* `x-credit-balance`: Your account's current balance.

Each endpoint's documentation provides a breakdown of specific costs:

* [Ghg Emissions](/api/ghg-emissions.md) – *View pricing for absolute and intensity datasets.*
* [Company](/api/company.md) – *View pricing for search and list operations.*

To top up your balance, please visit the [Billing Settings](https://tracenable.com/settings/billing).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tracenable.com/api/api-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.