# API-driven analytics integration

{% hint style="info" %}
**Target Audience**: Developers
{% endhint %}

{% hint style="info" %}
This method does not embed a Toucan AI UI component. Instead, it allows you to fetch analytics data (dashboards, charts, or results) directly from the backend via API and render it using your own UI components. This approach is best described as API-driven analytics integration, not embedding.
{% endhint %}

### TL;DR

Toucan AI supports a "headless" integration model where analytics data is fetched directly via API, allowing you to render visualizations using your own custom UI components.

***

### When to use this

Choose this method when you require total control over the user interface, need to combine Toucan AI data with other internal data sources, or must build complex interactivity not supported by standard UI components.

***

### Functional Overview

Unlike web component or SDK embedding, this approach does not include a Toucan AI user interface. Instead, your application acts as the presentation layer, requesting raw or structured data from the Toucan AI backend.

* **Direct API Interaction**: Use REST or GraphQL endpoints to retrieve dashboard configurations, chart metadata, or query results.
* **Token-Based Security**: Every request must be authorized with a server-generated embed token to maintain data isolation and RLS.
* **Client-Side Rendering**: Your application is responsible for mapping the API response to your preferred charting library (e.g., D3.js, Chart.js, or Highcharts).

***

### Implementation Example

The following standard fetch request demonstrates how to retrieve dashboard data using a secure embed token:

```javascript
fetch('https://toucanai.cloud/api/v1/dashboards/your-dashboard-id', {
	method: 'GET',
	headers: {
		'Authorization': 'Bearer YOUR_EMBED_TOKEN'
	}
})
	.then(res => res.json())
	.then(data => {
		// Implement custom rendering logic here
		console.log(data);
	});
```

***

### Architectural Considerations

| Feature              | Impact                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| **Customization**    | Offers maximum flexibility for branding and custom user workflows.                                      |
| **Development Cost** | Requires significantly more engineering effort as you must manage rendering, state, and error handling. |
| **Interactivity**    | Enables advanced data manipulation and custom business logic beyond standard dashboard features.        |
| **Maintenance**      | Developers must monitor API schema updates and handle versioning in their own code.                     |


---

# 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.toucanai.cloud/embed/embedding-methods/api-based-embedding.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.