> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chartcastr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sources

> List the data sources connected to your Chartcastr account, including provider, status, and the number of connections using each source.

## Overview

A **source** is a configured data provider — Google Sheets, HubSpot, Shopify, Xero, etc. — owned by your account. Each source can be referenced by multiple connections (delivery schedules) and is the entry point for fetching the latest [pulse](/api/pulses).

The Sources endpoint returns the most recently updated sources for the authenticated account, including the provider, status, deep link to the dashboard, and a count of connections currently using it.

## Endpoint

<AccordionGroup>
  <Accordion title="GET /v1/sources — list sources" icon="database">
    Returns up to 10 of the most recently updated, non-archived sources for the account behind the API key.

    **Request**

    ```bash theme={null}
    curl https://public.api.chartcastr.com/v1/sources \
      -H "X-API-Key: sk_live_..."
    ```

    **Success — 200**

    ```json theme={null}
    {
      "meta": {
        "account": { "id": "acc_2abc...", "email": "you@example.com" },
        "requestedAt": "2026-05-08T10:31:48.000Z"
      },
      "sources": [
        {
          "id": "src_01J...",
          "name": "Q2 Revenue Sheet",
          "provider": "GOOGLE",
          "status": "ACTIVE",
          "link": "https://chartcastr.com/admin/sources/src_01J...",
          "connectionCount": 3,
          "organizationId": "org_01J...",
          "organizationName": "Acme",
          "organizationSlug": "acme"
        }
      ]
    }
    ```

    **Source fields**

    | Field              | Type           | Description                                                       |
    | ------------------ | -------------- | ----------------------------------------------------------------- |
    | `id`               | string         | Unique source ID — pass to `/v1/sources/{sourceId}/pulse`         |
    | `name`             | string \| null | User-supplied display name                                        |
    | `provider`         | string         | Integration provider, e.g. `GOOGLE`, `SHOPIFY`, `HUBSPOT`, `XERO` |
    | `status`           | enum           | `PENDING`, `DRAFT`, `ACTIVE`, `DEGRADED`, or `BROKEN`             |
    | `link`             | string         | Deep link to the source page in the Chartcastr admin              |
    | `connectionCount`  | integer        | How many connections (delivery schedules) use this source         |
    | `organizationId`   | string         | Internal organization ID this source belongs to                   |
    | `organizationName` | string \| null | Organization display name                                         |
    | `organizationSlug` | string \| null | Organization URL slug                                             |

    **Failure — 401**

    ```json theme={null}
    { "success": false, "error": "Invalid or expired API key" }
    ```

    <Note>
      Results are capped at 10 sources, ordered by `updatedAt` descending. If you need a complete inventory, contact support — pagination is on the roadmap.
    </Note>
  </Accordion>
</AccordionGroup>

## Status Values

| Status     | Meaning                                                    |
| ---------- | ---------------------------------------------------------- |
| `PENDING`  | Source created but not yet authorized                      |
| `DRAFT`    | Configured but not ready to deliver                        |
| `ACTIVE`   | Healthy and delivering on schedule                         |
| `DEGRADED` | Last few runs had issues — investigate the source page     |
| `BROKEN`   | Authorization or upstream API failure — needs reconnection |

## Example: Filter by provider

The endpoint returns all sources — filter client-side by `provider` if you only care about one integration:

```ts theme={null}
const res = await fetch('https://public.api.chartcastr.com/v1/sources', {
  headers: { 'X-API-Key': process.env.CHARTCASTR_KEY! },
})
const { sources } = await res.json()
const shopify = sources.filter((s) => s.provider === 'SHOPIFY')
```

## Next Steps

<Card title="Fetch the Latest Pulse" icon="chart-line" href="/api/pulses">
  Pass any `id` from this list to the Pulses endpoint to get the chart, short summary, and long AI analysis.
</Card>