> ## 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.

# Pulses

> Fetch the latest pulse for a source — the chart image, short AI summary, and long AI analysis from the most recent successful job run.

## Overview

A **pulse** is a single delivered run for a source: a rendered chart image plus the AI-generated commentary that goes with it. The Pulses endpoints return the most recent successful pulse — across any of the source's connections — so you always get the freshest analysis.

Fetch a pulse by **source ID** — get the ID from `GET /v1/sources`.

## Endpoints

<AccordionGroup>
  <Accordion title="GET /v1/sources/{sourceId}/pulse — latest pulse for a source" icon="chart-line">
    Returns the most recent `SUCCESS` job run for the given source, including the chart image URL and both AI summaries.

    **Request**

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

    **Path parameters**

    | Parameter  | Type   | Description                      |
    | ---------- | ------ | -------------------------------- |
    | `sourceId` | string | Source ID from `GET /v1/sources` |

    **Success — 200**

    ```json theme={null}
    {
      "meta": {
        "account": { "id": "acc_2abc...", "email": "you@example.com" },
        "requestedAt": "2026-05-08T10:31:48.000Z"
      },
      "pulse": {
        "jobRunId": "run_01J...",
        "sourceId": "src_01J...",
        "sourceName": "Q2 Revenue Sheet",
        "status": "SUCCESS",
        "completedAt": "2026-05-08T09:00:12.000Z",
        "imageUrl": "https://cdn.chartcastr.com/charts/...",
        "aiSummaryShort": "Revenue up 12% week-over-week, driven by enterprise tier.",
        "aiSummaryLong": "Weekly revenue grew from $48,200 to $54,000...",
        "deliveryLink": "https://acme.slack.com/archives/C123/p17152...",
        "organizationId": "org_01J...",
        "organizationName": "Acme",
        "organizationSlug": "acme"
      }
    }
    ```

    **Pulse fields**

    | Field              | Type             | Description                                                |
    | ------------------ | ---------------- | ---------------------------------------------------------- |
    | `jobRunId`         | string           | Unique ID of the successful job run                        |
    | `sourceId`         | string           | Source this pulse belongs to                               |
    | `sourceName`       | string \| null   | Source display name at the time of the run                 |
    | `status`           | string           | Always `SUCCESS` (only successful runs are returned)       |
    | `completedAt`      | datetime \| null | When the job finished                                      |
    | `imageUrl`         | string \| null   | Rendered chart image (PNG)                                 |
    | `aiSummaryShort`   | string \| null   | One-line AI commentary — good for previews                 |
    | `aiSummaryLong`    | string \| null   | Full AI analysis — good for embedded reports               |
    | `deliveryLink`     | string \| null   | Link to the delivered Slack message (if Slack destination) |
    | `organizationId`   | string           | Internal organization ID                                   |
    | `organizationName` | string \| null   | Organization display name                                  |
    | `organizationSlug` | string \| null   | Organization URL slug                                      |

    **Failure — 404**

    ```json theme={null}
    { "success": false, "error": "No pulse found for this source" }
    ```

    Returned when the source exists but has never produced a successful run.
  </Accordion>
</AccordionGroup>

## Image URLs

`imageUrl` points to a rendered chart PNG hosted on Chartcastr's CDN. Links are durable for delivered pulses and can be embedded directly in dashboards, Notion, or anywhere that accepts a public image URL.

## Example: Embed the latest analysis

```ts theme={null}
const id = 'src_01J...'
const res = await fetch(
  `https://public.api.chartcastr.com/v1/sources/${id}/pulse`,
  { headers: { 'X-API-Key': process.env.CHARTCASTR_KEY! } },
)
const { pulse } = await res.json()

return `
  <img src="${pulse.imageUrl}" alt="${pulse.sourceName}" />
  <p><strong>${pulse.aiSummaryShort}</strong></p>
  <details><summary>Full analysis</summary>${pulse.aiSummaryLong}</details>
`
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Overview" icon="book" href="/api/overview">
    Auth, rate limits, and the OpenAPI spec.
  </Card>

  <Card title="AI Tools" icon="robot" href="/integrations/ai-tools">
    Use the same key with Claude, ChatGPT, Cursor, or Codex via MCP.
  </Card>
</CardGroup>