# Agency workspaces Source: https://docs.chartcastr.com/admin/agency-workspaces Manage multiple client accounts from a single Chartcastr dashboard with consolidated billing and shared integrations. Agency workspaces let you manage multiple client accounts from one parent organization. Each client gets their own isolated workspace with separate data, connections, and members, while billing consolidates to a single invoice on the parent account. ## Getting started Agency workspaces require the **Agency plan**. To upgrade: Reach out via [the agency page](/agencies) or email [support@chartcastr.com](mailto:support@chartcastr.com) to discuss your needs and get set up on the Agency plan. Once activated, your existing organization becomes the **parent agency workspace**. All billing flows through this account. Navigate to **Admin > Agency** in the sidebar. Click **Create client** to launch the setup wizard. ## Creating a client workspace The Create Client wizard walks through four steps: 1. **Name** -- enter your client's business name (e.g. "Harvey Norman", "JB Hi-Fi") 2. **Branding** -- add the client's domain to auto-fetch their logo, or upload one manually 3. **Invite** -- add team members by email and assign admin or member roles 4. **Review** -- confirm details and create the workspace Once created, the client workspace appears in your sidebar under **Clients**. Switch between workspaces with a single click. ## Sidebar navigation The sidebar adapts based on your workspace type: * **Agency parent**: Shows a "Clients" section listing all child workspaces with a quick-switch combobox * **Client workspace**: Shows a "Back to \[agency]" link and a sibling switcher if you have access to multiple clients ## Shared Slack setup Instead of installing Chartcastr's Slack app separately in each client workspace, you can **delegate** your parent Slack integration: 1. Install the Chartcastr Slack app in your agency's Slack workspace (if not already done) 2. Navigate to a client workspace's settings 3. Click **Delegate parent's Slack** 4. Select which Slack channels the client workspace can deliver to Channel allowlists prevent client workspaces from accessing agency-internal channels. Each client only sees the channels you explicitly grant. ## Billing * **One invoice** covers all client workspaces -- no separate billing per client * Each active client workspace is billed at a per-workspace rate ($20--$40/month depending on tier) * **Paused** client workspaces are not billed * Per-client tiers (Starter, Pro, Enterprise) and coupons can be set from the Agency dashboard * View per-client contribution breakdowns on the **Invoices** tab ## Managing client workspaces From **Admin > Agency** you can: * **Pause / unpause** a client workspace (stops billing, preserves data) * **Set billing tier** per client (Starter, Pro, Enterprise) * **Apply coupons** per client for discounted rates * **Detach** a client workspace (severs the parent-child link) * **Request access** to a client workspace you haven't joined yet ## Limits * Default limit: **10 client workspaces** per agency * Each child workspace inherits the full Pro-tier feature set * Workspaces are fully isolated -- data, connections, and members don't cross between clients * Need more than 10 clients? [Get in touch](/agencies) ## Related docs The full agency model explained. Step-by-step guide to setting up your agency. Pricing, invoices, and per-client tiers. Create, pause, and configure client workspaces. # Invoices Source: https://docs.chartcastr.com/admin/billing/invoices Access, view, and download PDF invoices for your Chartcastr subscription. Manage billing details and track your organization payment history. ## Overview Manage your billing history and download past invoices for your records. ## How to Access You can view and download all your past invoices in the Billing section of your organization settings. 1. Go to [Billing](https://chartcastr.com/admin/manage/org/organization-billing). 2. Click on the **Invoices** tab or section. 3. You will see a list of all past transactions. 4. Click **Download** on any invoice to get a PDF version. ## Billing Details You can update the billing address and email shown on your invoices in the **Billing Settings** section. # Payment methods Source: https://docs.chartcastr.com/admin/billing/payment-methods Add, update, or remove credit cards and payment methods on your Chartcastr account. All payments are securely processed through Stripe. ## Overview Manage the credit cards and payment methods associated with your Chartcastr account. ## How to Update To update your credit card or change your primary payment method: 1. Go to [Billing](https://chartcastr.com/admin/manage/org/organization-billing). 2. Click on **Payment Methods**. 3. Click **Add Payment Method** to add a new card. 4. To remove a card, click the trash icon next to it (provided you have another valid card on file if on a paid plan). ## Security We use **Stripe** for secure payment processing. Your full credit card details are never stored on our servers. # Subscription plans Source: https://docs.chartcastr.com/admin/billing/plans Compare Chartcastr Free, Starter, Pro, and Enterprise plans. Upgrade or downgrade anytime to match your team size and feature needs. ## Overview Chartcastr offers several plans tailored to different needs, from individual developers to large enterprises. ## Available Plans * **Free**: Forwarder-only. Up to 2 metrics from any integration, delivered on a daily schedule to Slack, email, Teams, or Google Chat. No AI summaries, chat, or follow-ups. No credit card to enter. * **Starter**: All paid features at entry-level limits — AI summaries on every pulse, AI chat, AI follow-ups, 10 active Slack connections, 14-day free trial (card required to start). * **Pro**: Unlimited connections, unlimited AI, granular scheduling, webhooks, and priority support. * **Enterprise**: Custom limits, BYOK, dedicated account management, and SLAs. For a full comparison, visit our [pricing page](https://chartcastr.com/pricing). ## Changing Plans You can upgrade or downgrade your plan at any time in [Billing](https://chartcastr.com/admin/manage/org/organization-billing). Use the button below to manage your subscription directly in the app. # Connections Source: https://docs.chartcastr.com/admin/connections Create and manage connections that link data sources to destinations like Slack, Teams, and email. Configure schedules, AI summaries, and delivery options. ## Overview Connections link your data sources to destinations, enabling automatic chart delivery. Each connection defines what chart to fetch, where to send it, and when to deliver it. ## Connection Components A connection consists of: 1. **Source**: Where the chart comes from (Google Sheets, HubSpot, Shopify, etc.) 2. **Destination**: Where to send it (Slack, Teams, Email, etc.) 3. **Schedule**: When and how often to send 4. **Configuration**: Message format, AI summary, and other options 5. **Context**: Extra text context about this chart or group. ## Creating a Connection Select an existing source or create a new one Select where to send the chart Set up when and how often to send Configure message format and options Send a test delivery to verify setup Enable the connection to start automatic delivery ## Connection List The Connections page shows all your configured connections: | Column | Description | | --------------- | --------------------------------- | | **Name** | Connection display name | | **Source** | Data source (Google Sheets, etc.) | | **Destination** | Where charts are sent | | **Schedule** | Frequency of delivery | | **Status** | Active, Paused, or Error | | **Last Run** | Most recent delivery time | | **Next Run** | Upcoming scheduled delivery | | **Actions** | Test, Edit, Pause, Delete | ## Schedule Configuration When creating or editing a connection, you can configure how often charts are delivered. The following frequency options are available: ### Frequency Options | Option | Description | | --------------- | -------------------------------------------------------- | | **Every Hour** | Delivers once per hour, on the hour | | **Every Day** | Delivers once per day at a specific time | | **Every Week** | Delivers on selected days of the week at a specific time | | **Every Month** | Delivers once per month with flexible day options | ### Monthly Day Options When using the **Every Month** frequency, you can choose from three day-of-month options: Choose a specific day of the month (1–27) for delivery. If you need end-of-month delivery, use the "Last Day" option instead. Delivers on the first weekday (Monday–Friday) of each month. If the 1st of the month falls on a weekend, delivery automatically moves to the following Monday. **Examples:** * If the 1st is a Tuesday → delivers on the 1st * If the 1st is a Saturday → delivers on the 3rd (Monday) * If the 1st is a Sunday → delivers on the 2nd (Monday) Delivers on the last calendar day of each month, regardless of how many days the month has. ### Time and Timezone All schedule times use your organization's configured timezone. You can set your timezone in [Settings → Organisation](https://chartcastr.com/admin/settings?highlight=timezone). ## Plans & Premium Integrations All users can set up connections with any integration — including configuring, testing, and previewing chart delivery. However, some integrations (such as Shopify, Meta Ads, Xero, Google Search Console, Google Ads, and HubSpot) are premium and require a paid plan to activate. If you're on the free plan, connections using premium integrations will be created but cannot be enabled until you upgrade. You'll see an error message when attempting to activate them. Some integrations are currently in **private beta** and may require an invitation to access. Contact us if you're interested in early access. ## Connection Status Running normally on schedule Temporarily disabled Requires attention ## Next Steps Connect Google Sheets or other data providers. Configure Slack, Teams, or Email for chart delivery. # Admin dashboard Source: https://docs.chartcastr.com/admin/dashboard Your central hub for managing Chartcastr connections, organization settings, team members, and billing from a single dashboard view. The Admin Dashboard is your central hub for managing all aspects of Chartcastr. From here you can manage your data connections, configure organizational settings, and track your subscription. Manage your active data sources and delivery destinations. Configure organization-wide settings like Pulse Thread Linking and AI Language. Invite members, manage your profile, and handle organizational updates. View plans, manage invoices, and update payment methods. ## Next Steps Connect a source to a destination to start automating your visual insights. Fine-tune your AI analysis and organizational preferences. # Add email addresses Source: https://docs.chartcastr.com/admin/manage/add-emails Add and verify additional email addresses for your Chartcastr organization to use for notifications, billing, and member management purposes. ## Overview Add additional email addresses to your organization for notifications, billing, or member management. ## How to Add 1. Go to [Manage → Organisation Profile](https://chartcastr.com/admin/manage/org/organization-general) (or the Notifications tab). 2. Look for the **Email Addresses** section. 3. Click **+ Add Email**. 4. Enter and verify the new email address. # Archived items Source: https://docs.chartcastr.com/admin/manage/archived-items Archive and restore Chartcastr sources and connections. Stop scheduled deliveries while preserving configuration and historical data for later use. ## Overview When you no longer need a source or a connection but want to keep its configuration or historical data, you can **Archive** it. Archiving removes the item from your active lists but keeps it available for future restoration if needed. ## Archiving a Connection Connections can be archived at any time. Archiving a connection will immediately stop all scheduled deliveries associated with it. 1. Go to [Connections](https://chartcastr.com/admin/connections). 2. Locate the connection you wish to archive. 3. Click the **Archive** button (or select it from the actions menu). ## Archiving a Source To maintain data integrity, a source can only be archived if it has **no active connections** pointing to it. If you try to archive a source that still has active connections, you will be prompted to archive those connections first. 1. Go to [Sources](https://chartcastr.com/admin/sources). 2. Ensure all connections linked to this source are archived or deleted. 3. Click the **Archive** button on the source. ## Finding Archived Items Archived items are hidden by default to keep your active workspace clean. You can find them by clicking the "See archived..." links located at the bottom of the Sources and Connections pages. ## Resurrecting Items If you desperately need to restore an archived item: 1. Navigate to the archived items list (see above). 2. Locate the archived source or connection. 3. Click the **Restore** or **Resurrect** button. 4. The item will move back to your active list and resumes its previous configuration. Sources should usually be restored before their associated connections if you plan on re-activating the entire pipeline. # Google account connection Source: https://docs.chartcastr.com/admin/manage/google-account Manage the Google account linked to Chartcastr for Sheets, Docs, and Drive access. Understand the impact of disconnecting on your active pulses. ## Overview Chartcastr uses your Google account to access data from Google Drive, Sheets, and Docs. Managing this connection is critical for the continued functioning of your pulses. ## Connection Status You can view your connected Google account in [Manage → Connected Accounts](https://chartcastr.com/admin/manage/account). ## Impact of Removal **Profound Impact**: Removing or disconnecting your Google account will immediately break all pulses and connections that rely on Google-based data sources. This includes: * **Google Sheets connections**: Any pulse fetching data from a sheet will fail. * **Google Docs/Sheets Context**: Any pulse using Google Drive files for [External Context](/analysis/context/overview) will lose that context, potentially degrading AI analysis quality. ## Best Practices * Ensure the connected Google account has access to all the files you intend to use. * If you need to switch accounts, re-link your sources immediately to minimize downtime. # Invite team members Source: https://docs.chartcastr.com/admin/manage/invite-members Invite colleagues to your Chartcastr organization by email. Assign Admin or Member roles to control access to pulses, connections, and settings. ## Overview Collaborate with your team by inviting them to your Chartcastr organization. Invited members will have access to view and manage pulses, connections, and settings according to their role. ## How to Invite 1. Go to [Manage → Members](https://chartcastr.com/admin/manage/org/organization-members). 2. Click **Invite Member**. 3. Enter the email address of the person you want to invite. 4. Select a role (e.g., Admin or Member). 5. Click **Send Invitation**. Team members will receive an email with a link to join your organization. # Leave an organization Source: https://docs.chartcastr.com/admin/manage/leave-org Leave your current Chartcastr organization, understand admin restrictions on departure, and learn how to regain access if you need to return. ## Overview If you no longer need access to an organization, you can choose to leave it. **Important**: If you are the last admin of an organization, you may not be able to leave until you promote another member to Admin or delete the organization. ## How to Leave 1. Go to [Manage → Organisation Profile](https://chartcastr.com/admin/manage/org/organization-general). 2. Scroll to the bottom and click **Leave Organisation**. 3. Confirm your choice in the dialog. ## Getting Back In If you leave an organization and no one else has access to grant you entry, you may lose access permanently. To get back into an organization after leaving (if there are no other admins), you may have to contact **Chartcastr Support** to be manually re-added. # Update organization profile image Source: https://docs.chartcastr.com/admin/manage/update-profile-image Upload a custom profile image for your Chartcastr organization. This image appears in the sidebar and notification messages to identify your workspace. ## Overview Personalize your workspace by uploading an organization profile image. This image appears in the sidebar and in notifications to help identify your workspace. ## How to Update 1. Go to [Manage → Organisation Profile](https://chartcastr.com/admin/manage/org/organization-general). 2. Click on the profile image or the **Edit** button. 3. Upload a square image (PNG or JPG recommended). 4. Save your changes. # Usage and limits Source: https://docs.chartcastr.com/admin/manage/usage Monitor AI chat messages, monthly pulse deliveries, and AI analysis quotas in real time. View plan limits for your Chartcastr organization. ## Overview Manage your workspace effectively by monitoring your organization's usage. Chartcastr provides a real-time view of your metered features, deliveries, and AI consumption. You can access your current usage stats at [Manage → Usage](https://chartcastr.com/admin/manage/usage). ## Metered Features Chartcastr tracks several core features to ensure fair use and platform stability. ### AI Chat Messages Usage is tracked on a daily basis. Each message sent to the AI Chat counts towards your daily quota. * **Daily Reset**: Your message count resets every 24 hours. * **Tier Limits**: Limits vary depending on whether you are on the Free, Starter, or Pro plan. ### Monthly Deliveries (Pulses) This tracks the total number of pulse deliveries (Slack messages, Teams messages, or Emails) sent in the last 30 days. * **Rolling View**: This is a rolling 30-day window, not a calendar month reset. ### AI Analyses Tracks the number of AI-powered insights generated across your connections and pulses. This includes automated summaries and deep-dive analysis. ## Plan Features & Restrictions Different tiers of Chartcastr provide different levels of access. You can view the full comparison table in your dashboard. ### Key Categories | Category | Description | | :--------- | :----------------------------------------------------------- | | **Limits** | Maximum number of connections, sources, and seats. | | **AI** | Access to advanced models (Claude 3.5/4) and message quotas. | | **Pulses** | Frequency and volume of automated deliveries. | ## AI Quotas & BYOK We use high-performance LLMs to analyze your data. Each analysis consumes tokens which we aggregate into your daily message quotas. ### Bring Your Own Key (BYOK) If you require significantly higher volume or want to bypass platform AI limits, the **Pro tier** allows you to "Bring Your Own Key". This lets you plug in your own Anthropic or OpenAI API keys to power Chartcastr's AI features directly. ## Need Higher Limits? If you find yourself hitting your limits frequently, consider [upgrading to a higher plan](https://chartcastr.com/admin/upgrade) to gain access to unlimited connections and higher quotas. # Pulse Score Source: https://docs.chartcastr.com/admin/pulse-score An AI-generated 0-100 business performance snapshot covering growth, efficiency, marketing, product, and financial health category scores. Pulse Score is Chartcastr's AI-generated snapshot of how your business is performing based on the connected sources in your workspace. It combines recent data coverage, category scoring, and AI-written narrative into a report you can review internally or publish as a public profile. ## What It Includes Each Pulse Score report includes: * **Overall score**: A 0-100 summary of your current performance snapshot * **Category breakdowns**: Separate scores and grades for Growth, Efficiency, Product, Marketing, and Financial health * **Public narrative**: A concise summary written for external sharing * **Private insights**: Internal-only observations and recommended actions * **Coverage window**: The time period used for the current analysis ## How It Works Pulse Score runs automatically from your connected workspace data. 1. Chartcastr gathers the latest eligible source data for your organization. 2. AI analyzes that data across the Pulse Score categories. 3. Chartcastr generates an overall score, category scores, public narrative, and private recommendations. 4. The latest completed analysis becomes the version shown in your workspace. Pulse Score is no longer intended as a manual reporting workflow. The main experience is an automatically refreshed score built from your connected data. ## What You Can Do In The Admin Page The [`/admin/pulse-score`](https://chartcastr.com/admin/pulse-score) page combines internal review and publishing controls in one place. ### Internal Review Use the internal review section to: * Inspect the latest overall score * Switch between numeric scores and letter grades * Review the analysis coverage period * Read the AI-generated public narrative * See private insights and recommended actions ### Public Profile Preview Pulse Score can also be published as a public profile at `chartcastr.com/pulse/{your-slug}`. When visibility is on, your profile is also listed in the [Pulse Score Directory](https://chartcastr.com/pulse) — a public index of organizations sharing their scores openly. From the admin page you can: * Preview the public-facing version before publishing * Open the live public page when visibility is enabled * Copy the public link for sharing * Share directly to LinkedIn, X, or Reddit using the **Share** button ### Publishing Controls Pulse Score includes built-in controls for managing how your profile appears publicly. * **Public Visibility**: Turn your public profile on or off * **Public URL slug**: Choose the URL used for your public Pulse Score page (rate-limited to one change per week once set) * **Website link**: Add an external link displayed on the public profile (paid plans) * **Organisation logo**: Reuse your workspace logo on the public page Your public profile only shows the overall score, category grades, and AI-generated narrative. Private insights and recommended actions are never exposed publicly. ## Public Metric Sharing The Pulse Score admin includes a dedicated **Public Metric Sharing** tab. Each public metric page is powered by a real `PUBLIC_METRIC_PULSE` destination + connection, so it inherits the same scheduling, run history, and cache-refresh behavior as other connections. * **Share path**: Each pulse is accessible at `/pulse/{your-org-slug}/{pulse-slug}`. * **Auto slug**: The pulse slug is generated from the pulse name by default, then stored on the destination metadata and pulse record. * **Cached snapshot**: Successful/unchanged scheduled runs refresh the public metric snapshot cache (chart metadata, key metrics, AI narrative, and share image). * **Pulse Score tab role**: Pulse Score acts as an index and quick-action surface (visibility toggle, copy link, regenerate, open destination/connection). ### Create Flow 1. Start in **Connections** and create a new connection. 2. Pick a source or source group. 3. Choose **Public Metric Pulse** as destination type. 4. Save the connection. The system creates/updates the linked public pulse automatically. 5. Configure local pulse settings from destination or connection detail pages. By default, Public Metric Pulse connections start on a weekly schedule (`Sunday 00:00`) and can be adjusted from the connection page. ### Global Vs Local Config * **Global (org-level)**: Managed in Organisation Settings (`highlight=pulse-score`) and linked from [`/admin/pulse-score`](https://chartcastr.com/admin/pulse-score). This controls Pulse Score public profile defaults. * **Local (destination/connection-level)**: Managed on the `PUBLIC_METRIC_PULSE` destination and its connection. This controls pulse name, slug, description, highlight color, visibility, and run cadence/history for that specific public metric page. Use the [`/admin/pulse-score`](https://chartcastr.com/admin/pulse-score) page to monitor all public pulses and jump into destination/connection pages for edits. ## Scoring Model Pulse Score currently evaluates five categories: * **Growth**: Signals related to momentum, pipeline, and expansion * **Efficiency**: How effectively the business converts activity into results * **Product**: Product adoption, usage, or retention-oriented indicators * **Marketing**: Acquisition and campaign performance signals * **Financial**: Revenue and financial health indicators where available The exact inputs vary depending on which sources are connected and what data is available in your workspace. More connected sources generally give the AI more context and improve the quality of the resulting narrative and recommendations. ## Public Vs Internal Data Not everything in Pulse Score is meant for external audiences. * **Public profile**: Overall score, category breakdown, and public narrative * **Internal workspace view**: Everything above, plus private insights and recommended actions This lets you share a polished public snapshot while keeping more candid operational guidance inside your workspace. ## Refresh Timing Pulse Score refreshes automatically as new connected data becomes available. The page also shows when the latest completed analysis was updated and the date range used for that analysis. If you do not see a score yet, your organization may still be waiting for the first automatic run to complete. ## Related Docs Learn how scheduled updates and AI summaries flow through Chartcastr. Understand the rest of the workspace navigation and admin surface. Browse public Pulse Scores from organizations sharing their performance openly. Set up source connections that power your Pulse Score analysis. # Pulses Source: https://docs.chartcastr.com/admin/pulses Pulses are scheduled chart deliveries enriched with AI analysis. Learn how data fetching, AI summaries, and delivery scheduling work together. Pulses are the heartbeat of Chartcastr. They represent the automated flow of data from your sources to your destinations, enriched with AI analysis. ## The Data/Chart When a pulse triggers, Chartcastr fetches the latest data from your connected source (e.g., Google Sheets, HubSpot, Shopify). This data is then visualized according to your configuration, creating a snapshot of your key metrics at that specific moment in time. ## AI Summaries Available on > Starter plans only Beyond just raw data, Chartcastr uses AI to analyze the trends and changes in your data. The AI generates a concise summary, highlighting significant movements, anomalies, or "business as usual" states, giving you immediate context without needing to deep-dive into the numbers. ## Scheduling / Timing You can schedule pulses to run at specific intervals (e.g., daily at 9:00 AM, weekly on Mondays). **Timing Best Practice** Ensure that your source data (e.g., your Connected Sheet refresh or your spreadsheet update) refreshes well **BEFORE** the Chartcastr pulse is scheduled to kick off. This ensures your pulse always captures the freshest data. ## Next Steps Ask contextual questions about pulses in your Slack threads. Group sources together for unified analysis. # AI summary locale Source: https://docs.chartcastr.com/admin/settings/locale Choose the language, tone, and regional date or currency format for AI-generated pulse summaries. Applies organization-wide in Chartcastr. ## Overview The AI Summary Locale setting determines the language, tone, and formatting (such as date and currency formats) used by the AI when generating your pulse summaries. While the dropdown offers a curated list of common locales, the AI can communicate in most languages. English tends to produce the best results, but the AI will do its best to return summaries and chat responses in whichever language you specify. ## Configuration **Organization Setting**: This configuration is applied across your entire organization and affects all team members. You can update the AI Language and regional formats in your organization settings. 1. Go to [Settings → Organisation Settings](https://chartcastr.com/admin/settings?highlight=ai-language). 2. Locate the **AI Language** option. 3. Select your desired locale from the supported list (e.g., English (US), English (UK), Spanish, etc.). 4. Click **Save Changes**. ## Impact This setting affects: * The language of the AI summary text. * Numerical formatting (e.g., use of commas vs. periods). * Currency symbols if inferred from the data. # Pulse thread cross-linking Source: https://docs.chartcastr.com/admin/settings/pulse-thread-linking Automatically link consecutive pulse deliveries in Slack threads so your team can navigate forward and backward through data history. ## Overview Pulse Thread Cross-Linking allows you to maintain continuity in your Slack channels by linking consecutive pulse deliveries together. ## How it Works When enabled, Chartcastr will automatically: 1. Add a link to the **previous** pulse in the current pulse's thread. 2. Add a link to the **next** pulse in the previous pulse's thread once it is delivered. This creates a navigable history of your data directly within Slack. ## Configuration **Organization Setting**: This configuration is applied across your entire organization and affects all team members. You can configure Pulse Thread Cross-Linking in your organization settings. 1. Go to [Settings → Organisation Settings](https://chartcastr.com/admin/settings?highlight=pulse-thread-linking). 2. Find the **Pulse Thread Cross-Linking** section. 3. Select your preferred mode (Both Directions, Backward Only, Forward Only, or Disabled). # Schedule timezone Source: https://docs.chartcastr.com/admin/settings/timezone Set the timezone that controls when pulse schedules fire across your Chartcastr organization. Defaults to auto-detected timezone or UTC. ## Overview The Schedule Timezone setting determines how all pulse schedule times are interpreted. For example, if you set your schedule to "9 AM daily" and your timezone is set to `America/New_York`, pulses will fire at 9 AM Eastern Time. ## Default When your organisation is first created, Chartcastr will try its best to discover your preferred timezone automatically. We recommend double-checking that it was detected correctly in your [Organisation Settings](/admin/settings). If we couldn't determine it, schedules will default to **UTC**. ## Configuration **Organization Setting**: This configuration is applied across your entire organization and affects all connections and team members. 1. Go to [Settings → Organisation Settings](https://chartcastr.com/admin/settings). 2. Locate the **Schedule Timezone** section. 3. Search for and select your desired timezone (e.g., `America/New_York`, `Europe/London`). The change takes effect immediately for all future scheduled pulses. ## Impact This setting affects: * When scheduled pulses fire (e.g. "9 AM daily" is interpreted in the selected timezone). * All connections across the organisation use the same timezone. * Existing schedules are not modified — only the timezone interpretation changes. # Source groups Source: https://docs.chartcastr.com/admin/sources/source-groups Organize related data sources into logical groups for shared AI analysis, group-level summaries, and unified external context in Chartcastr. ## Overview Source Groups are a powerful way to organize your individual data sources into logical buckets. Instead of managing dozens of independent sources, you can group related sources (e.g., "Main Marketing KPIs", "Sales Pipeline", "Product Health") under a single label. ## Why Use Source Groups? Keep your workspace clean and organized by categorizing sources into relevant business areas. Providing the AI with the group context allows it to understand how disparate data points relate to each other. Source groups can have their own summaries, helping you track high-level trends across multiple charts. Assign [External Context](/analysis/context/overview) to a group once instead of to every individual source. ## Managing Source Groups You can create and manage your Source Groups in the admin settings. 1. Navigate to [Settings](https://chartcastr.com/admin/settings). 2. Click **Manage** on the **Groups** card. 3. Click **+ New Source Group** or edit an existing one. 4. Give your group a name (e.g., "Executive Dashboard") and an optional description. 5. Select the individual sources you want to include in this group. ## AI Benefits When a pulse belongs to a source that is part of a group: * **Cross-Source Awareness**: The AI "knows" what other sources are in the same group. * **Categorization**: Analysis will reflect the group's label, providing clearer context in Slack or Email. * **Contextual Reasoning**: If Source A and Source B are both in "Marketing Spend", the AI can correlate drops in one with rises in the other more effectively. ## External Context Integration Assigning a document (like a strategy PDF or a Glossary) to a Source Group means that **every source** in that group inherits that context. This is the most efficient way to provide business logic to related datasets. Read more about [External Context](/analysis/context/overview). # Agency billing Source: https://docs.chartcastr.com/agencies/billing How billing works for agencies: a flat platform fee plus a per-active-client charge, billed monthly to the parent agency org. ## Two-line pricing Agency billing has two components, both invoiced monthly to the **parent agency org**: 1. **Platform fee** — \$380/mo flat, on the parent's Clerk subscription. Unlocks the agency multi-workspace surface (sidebar, dashboard, cross-client switching, the agency dashboard). 2. **Per-active-client charge** — pay only for workspaces you actually use. Each client workspace is on one of three billing tiers: | Tier | Rate / active client / mo | Use for | | ---------- | ------------------------- | ---------------------------------------- | | Starter | \$20 | Light usage, single source, fewer pulses | | Pro | \$40 | Default — most paying clients | | Enterprise | Custom | High-volume, custom integrations, SLA | The variable line is metered: you're billed for the days a workspace was active in the month. Pause a workspace and billing stops immediately. ``` Parent agency → Stripe customer ├─ Clerk subscription: $380 platform fee (flat) └─ Metered subscription: per-active-client (variable) ``` You'll see one Stripe invoice each billing cycle covering both lines, regardless of how many client workspaces you have. ## Active vs. paused A child workspace is "active" for a billing day when it's: * attached to your agency (not [detached](/agencies/managing-clients#detaching-a-client)), and * not paused (Organization is `active`) Paused workspaces stop billing immediately and their pulses don't fire. Unpause anytime — billing resumes on the next daily snapshot. Only agency admins (and Chartcastr staff) can pause or unpause a workspace from the agency dashboard. ## What children get Each child workspace receives the **Pro-tier** feature set regardless of which billing tier you put them on (the tier is purely a pricing knob, not a feature gate): * Unlimited sources * Unlimited pulses per month * Unlimited Slack channel connections (+ Slack Connect) * Email & Google Chat destinations * AI summaries, AI chat (100 messages/day), follow-ups * All premium integrations (Shopify, Xero, Meta Ads, Google Ads, HubSpot, etc.) Each workspace gets these limits **independently** — heavy usage in one client doesn't starve another. ## Choosing a child billing tier You assign a tier from the **Settings → Agency** dashboard, in the workspace row. Changing the tier takes effect on the next daily billing snapshot — there's no proration noise mid-day. ## What the agency parent gets Your parent agency org is itself a Pro-equivalent workspace — useful for hosting your own internal pulses (e.g. "new MRR this week" or "client retention overview"). Use it for cross-client rollups or for client-acquisition reporting. ## Switching plans Only **admins on the parent agency org** can change the platform plan or pause/unpause client workspaces. Open **Settings → Organization → Billing** on the parent org to manage the \$380 platform subscription. Child workspaces see a "Billing managed by \{your agency}" notice in their Billing tab. ## Detaching a workspace When you [detach](/agencies/managing-clients#detaching-a-client) a child workspace, it becomes a standalone Chartcastr org on the **free tier**. The client retains access to their data; they can upgrade independently after that. Detached workspaces stop counting toward your variable line on the next billing snapshot. ## What if I cancel my Agency plan? If your Agency subscription lapses, the metered variable line is cancelled and every child workspace automatically reverts to free-tier limits (they keep their data but lose Pro features). Re-subscribing restores them in seconds. ## Custom pricing Volume discounts, agency-specific deals, and non-list per-child rates are handled via Stripe customer-level discounts — no code or plan-slug changes needed. [Reach out](/agencies#contact) for an Enterprise quote. # Agency limits Source: https://docs.chartcastr.com/agencies/limits Per-workspace and per-agency limits on the Agency plan. ## Workspace count The Agency plan supports **unlimited client workspaces**. Add as many clients as you need — billing scales per active workspace (see [Billing](./billing)). ## Per-workspace limits Each child workspace (and your parent agency org) gets the **Pro-tier** limits: | Resource | Limit per workspace | | -------------------------- | ------------------- | | Active sources | Unlimited | | Pulses per month | Unlimited | | Slack channel connections | Unlimited | | Slack Connect destinations | Available | | Email destinations | Unlimited | | AI chat messages | 100 / day | | AI follow-ups per pulse | Unlimited | | Active streams | Unlimited | | Stream events / month | Unlimited | | AI summaries / month | Unlimited | These limits are **independent per workspace** — heavy usage in one client doesn't consume another's allowance. ## Pausing workspaces Don't want to pay for a workspace this month? Pause it from the agency dashboard. A paused workspace stops billing immediately (variable charge) and its pulses don't fire. You can unpause anytime; existing data and configuration are preserved. Only agency admins and Chartcastr staff can pause/unpause workspaces. ## Member limits There is no agency-level cap on members. Each workspace's member count is governed by Clerk org limits (effectively unlimited for paid plans). ## Hitting a per-workspace limit Workspaces enforce limits at the source/connection/pulse level — you'll see a clear error in the UI when an action would exceed a workspace's limit. The agency dashboard surfaces aggregate usage so you can spot which workspace is hot. ## Enterprise If your agency needs: * Custom per-workspace pricing or volume discounts * SLA / dedicated support * SSO / SAML * Custom integrations * Audit log access …upgrade to **Enterprise** — [reach out](/agencies#contact). # Managing client workspaces Source: https://docs.chartcastr.com/agencies/managing-clients Create, switch between, request access to, and detach client workspaces from your agency. The **agency dashboard** at [/admin/agency](https://chartcastr.com/admin/agency) is the control surface for every client workspace under your agency parent. Anything beyond data ingestion (sources, connections, pulses) lives inside the child workspace itself — switch in to manage it. ## Creating a client Click **Create client** on the agency dashboard. You'll be asked for: * **Client name** — shown in the sidebar switcher and on every chart delivery. * **Slug** (optional) — URL identifier. Lowercase letters, numbers, dashes only. Auto-generated from the name if omitted. The new workspace appears immediately in the sidebar's **Agency** group. You're auto-added as **admin** of the new workspace. ## Switching between workspaces Two ways: 1. **Sidebar Agency group** — quick-switch entries for every workspace you're a member of. One click to jump in. 2. **Org switcher in the sidebar footer** — Clerk's full org switcher (every workspace you belong to, including ones outside the agency). Switching clears all cached data and reloads scoped to the new workspace — there's no risk of leaking data across clients. ## Requesting access to a workspace By default, only the **agency admin who created** a workspace is added to it. Other agency admins must self-invite from the agency dashboard: 1. On [/admin/agency](https://chartcastr.com/admin/agency), find the workspace. 2. Click **Get access** (visible only if you're not already a member). 3. You're added as an admin via Clerk. The workspace now shows up in your sidebar. This explicit access model gives you a clean audit trail of which agency members have touched which client. If you'd prefer auto-mirroring (every agency admin in every client workspace), [contact support](mailto:hi@chartcastr.com) — we can flip a flag per-account. ## Inviting a client to their workspace Inside the child workspace, open **Settings → Organization → Members** and use Clerk's invite flow. The client sees only their own workspace, with no view of your agency or other clients. ## Detaching a client If a client wants to take their reporting in-house, you can detach the workspace: 1. On [/admin/agency](https://chartcastr.com/admin/agency), find the workspace. 2. Click the unlink icon, then **Detach** in the confirm dialog. What happens: * The workspace becomes a **standalone** Chartcastr org on the **free tier**. * All members (including your agency admins) keep their access. * The workspace can upgrade independently to Starter/Pro from there. * It no longer counts against your agency child-workspace cap. You can re-attach a detached workspace by contacting support — automated re-attach is on the roadmap. ## Deleting a workspace Open the workspace itself, then **Settings → Organization → General → Delete**. Standard Clerk flow. You **cannot delete the parent agency org** while it has any child workspaces. Detach or delete all clients first. ## Cross-client data isolation Every database query, GraphQL resolver, and storage path is scoped to the active workspace's organization id. There is no "see everything across clients" view by design — for cross-client analytics, run a pulse in your **parent agency** workspace against your own metrics. # Agency overview Source: https://docs.chartcastr.com/agencies/overview How agencies use Chartcastr to manage multiple client workspaces from a single account, with one invoice and one team. Chartcastr Agency is for teams that deliver reporting to **multiple end-clients**. Instead of juggling separate accounts (and separate invoices) per client, you operate a single **parent agency org** that owns **child client workspaces**. ## The model ``` Your Agency (parent — billing lives here) ├─ Acme Co. (child workspace) ├─ Globex Corp. (child workspace) └─ Initech LLC (child workspace) ``` * **Billing only flows to the parent.** One invoice covers every client workspace. * **Children inherit the parent's plan.** Each child gets the full Pro-tier feature set (unlimited sources, unlimited pulses, AI features, Slack Connect, etc.). * **Up to 10 client workspaces** per agency on the default Agency plan. Larger agencies — [get in touch](/agencies#contact). * **Workspaces are isolated.** Data, members, and connections don't cross between clients. Switching workspaces is a single click in the sidebar. * **Explicit access.** Agency admins aren't auto-added to every client workspace — they request access per-workspace, or are invited directly. This keeps the audit trail clean. ## When this is the right fit * You build dashboards or reports for clients in **Slack, email, or Google Chat**. * You manage 3+ clients and want **one invoice instead of N**. * You want each client's **data, AI summaries, and connections** to live in a workspace that's clearly theirs (so you can hand it over later if they bring reporting in-house). ## What to read next * [Setting up your agency](/agencies/setup) * [Billing & limits](/agencies/billing) * [Managing client workspaces](/agencies/managing-clients) # Setting up your agency Source: https://docs.chartcastr.com/agencies/setup Step-by-step: subscribe to the Agency plan, create client workspaces, and invite teammates. This guide walks through getting your agency org and your first client workspace running. ## 1. Subscribe to the Agency plan Create your Chartcastr account at [chartcastr.com/sign-up](https://chartcastr.com/sign-up) (or sign in if you already have one). This first organization becomes your **parent agency org** — name it after your agency (e.g. "BigRock Reports"). From the sidebar, click **Upgrade** and pick the **Agency** plan. Billing is monthly or annual. If you don't see the Agency tier in the upgrade flow, [contact us](mailto:hi@chartcastr.com) — we'll provision it for your account. After checkout, the sidebar shows a new **Agency** group at the top with a link to **Agency home**. ## 2. Create your first client workspace Click **Agency home** in the sidebar, or visit [/admin/agency](https://chartcastr.com/admin/agency). Click **Create client**. Enter the client's name (e.g. "Acme Co.") and optionally a slug. The slug becomes the workspace's URL identifier (lowercase letters, numbers, dashes only). You're automatically added to the new workspace as an admin. The sidebar now shows it as a quick-switch entry. Click to switch in — the dashboard, sources, connections, and destinations are now scoped to that client. From the child workspace, open **Settings → Organization → Members** to invite the client's stakeholders. They'll see only their workspace. ## 3. Invite teammates to your agency Open **Settings → Organization → Members** on the **parent agency org** (not a child workspace) to invite your fellow agency admins. Teammates added to the parent **don't** automatically get access to every client workspace — they request access per-workspace from the agency dashboard, which keeps your client audit trail clean. ## Next steps * [Billing & limits](/agencies/billing) * [Managing client workspaces](/agencies/managing-clients) # The /admin/briefings page Source: https://docs.chartcastr.com/analysis/briefings/admin-page A short tour of the briefings list, composer, settings, and snapshot history pages inside Chartcastr. The **Briefings** entry in the sidebar takes you to your briefings list. Each briefing has its own composer, settings, and snapshot history. ## Pages | Page | What it's for | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **List** — `/admin/briefings` | All your briefings as a card grid, with status pills (`Up to date`, `Unsaved changes`, `Regenerating`, `Failed`) and a button to create a new one. | | **Composer** — `/admin/briefings/[id]` | Where you compose a briefing: edit the name and description, add rows and items, and press **Save** to regenerate the AI commentary. | | **Settings** — `/admin/briefings/[id]/settings` | Pick a [destination](/integrations/destinations), set the monthly delivery day and time, and toggle the briefing active or paused. | | **Snapshots** — `/admin/briefings/[id]/snapshots` | A history of past PDF runs, each with a download link and a frozen view of the briefing as it was delivered. | ## Composer at a glance The composer has three areas: * **Header** — name, description, **Save** and **Send Snapshot** buttons. * **Overall review** — the read-only AI synthesis sitting above the rows. * **Row list** — each row card shows its title, items, and per-row commentary, plus reorder controls and an "Add item" picker. A footer reminds you when there are unsaved changes. **Send Snapshot** is disabled while there are unsaved changes, while a save is regenerating, or while this month's snapshot has already been delivered. ## Related What a briefing is and the plan limits that apply. What happens when you press Save. # Overall review & AI commentary Source: https://docs.chartcastr.com/analysis/briefings/overall-review How Chartcastr generates the page-level overall summary, the per-row commentary, and the AI titles that sit above and inside a briefing. A briefing has three layers of AI text. Each layer is intentionally narrow in scope so prompt cost stays predictable and the results are easy to reason about. ## The three AI layers | Layer | Where it lives | Inputs | Cost shape | | ------------------ | ---------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | | **AI titles** | `Briefing.aiTitle` + `BriefingRow.aiTitle` | Briefing description, row items, item summaries | Single batched Haiku call, \~500–1,000 input / \~150 output tokens. | | **Row commentary** | `BriefingRowContent.aiCommentaryShort/Long + aiHighlights` | Just the items inside that row + their latest Pulse summary | One call per row, bounded concurrency (3 in flight). | | **Overall review** | `BriefingContent.aiSummaryShort/Long + aiHighlights` | The completed row commentaries + each item's short summary | One call per save, after all rows are done. | ## Overall review (the "big picture") The Overall Review sits at the top of the composer and on Page 2 of the PDF. It synthesises **across rows** — calling out themes that show up in multiple places, contradictions between rows, and what the user should pay attention to. It is regenerated **on every save** — there is no skip path. Even if every row was reused from cache, the overall summary still runs because (a) it depends on the row outputs, which may have shifted in tone, and (b) it's a single small call, so the savings would be marginal. The model gets: * The briefing name and description * For each row: title, the long commentary, the highlights * For each item across all rows: the short summary It produces: * `aiSummaryShort` — a 2-sentence executive summary * `aiSummaryLong` — the body of the "Big Picture" page (4–8 sentences) * `aiHighlights` — 2–4 bullet points The overall review is text-in / text-out — no images. Row commentary is also text-only in v1. The only place chart images are read by the AI is at the per-source Pulse layer, before the briefing ever sees them. ## Row commentary Each row's `aiCommentaryLong` is the analyst-style text shown on that row's card in the composer and under each row's "Cross-analysis" heading in the PDF. It synthesises **just** the items inside that row — there's no leakage from other rows. Row commentary uses a hash-based skip: if the row's items, their Pulse content IDs, and the row title haven't changed since the last successful run, the prior commentary is reused without an LLM call. See [Save & commit](/analysis/briefings/save-and-commit) for the full hash logic. ## AI titles Both `Briefing.aiTitle` and every `BriefingRow.aiTitle` regenerate in a single batched call to Haiku. The call is **skipped entirely** when: * A `aiTitleInputsHash` matches the freshly computed hash, AND * Both the briefing and every row already have a user-set title (nothing to fill in). The title prompt is told which titles are locked (`nameLockedByUser` / `titleLockedByUser`) and emits `null` for those — the composer keeps your typed title and never overwrites it. ### Reset to AI title If you typed a title and later want the AI version back, the row card and briefing header both expose a **Reset to AI title** action. This clears `nameLockedByUser` (or `titleLockedByUser`), and the next save regenerates the AI title. ## What you see in the composer ``` ┌───────────────────────────────────────────────────────────┐ │ Briefing name (yours, or AI) [Save] [Send] │ │ description │ ├───────────────────────────────────────────────────────────┤ │ Overall review (read-only AI text + highlights) │ │ "Regenerating…" while a save is in flight │ ├───────────────────────────────────────────────────────────┤ │ Row 1 — "Acquisition" (your title, or AI) │ │ [item] [item] [item] [+ Add item] │ │ Cross-analysis: row commentary + highlights │ ├───────────────────────────────────────────────────────────┤ │ Row 2 — … │ └───────────────────────────────────────────────────────────┘ ``` The overall review and per-row commentary are read-only — there's no human override on AI commentary text. If you want to steer the analysis, the lever is the briefing **description**: a one-paragraph framing that the AI receives at every layer and uses to prioritise what to call out. # Briefings overview Source: https://docs.chartcastr.com/analysis/briefings/overview Briefings stitch multiple sources and source groups into a single AI-synthesised dashboard, with a once-a-month PDF snapshot delivered to your destination. A **Briefing** is a cross-source AI synthesis surface. Where a Pulse delivers analysis for one source (or one source group) at a time, a Briefing combines many of them into a single big-picture view that runs **once per calendar month** and lands as a PDF in your destination. Briefings are available on **any paid plan** (Starter, Pro, Enterprise). Limits vary by tier — see [Plan limits](#plan-limits) below. ## What a Briefing is made of | Concept | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------- | | **Briefing** | The top-level container. Has a name, description, optional cover emoji + colour, a destination, and a monthly schedule. | | **Row** | A horizontal grouping of items the AI cross-analyses together. Think "Acquisition", "Retention", "Finance". | | **Row item** | One source or source group inside a row. Pulls in the latest chart image + AI summary from that source's most recent Pulse. | | **Overall review** | The page-level AI synthesis sitting above the rows — the "big picture" across every row. | | **Snapshot** | A frozen, versioned PDF of the briefing at a point in time. One snapshot per calendar month. | ## How it works at a glance 1. You compose the briefing in `/admin/briefings/[id]` — add rows, drop sources or source groups into each row, give them titles. 2. You press **Save** — the server runs a fresh AI pass: per-row commentary, then an overall summary across all rows. 3. Once committed, you can **send a snapshot** — Chartcastr renders a multi-page PDF and delivers it to your chosen destination. 4. A monthly cron fires the same flow automatically on your scheduled day-of-month + time. ## Pages in this section Playbooks for the four jobs Briefings nail first — client reporting, board prep, pitch prep, all-hands. How rows and row items work, what counts toward your per-row item budget, and how source groups expand inside a row. The page-level AI summary, per-row commentary, and how AI titles are generated. The explicit save model, AI regeneration, and why edits are blocked while a commit is in flight. Monthly PDF snapshots, the once-per-calendar-month throttle, and destination delivery. A walkthrough of the list view, composer, settings, and snapshot history pages. ## Plan limits Limits scale with your tier. Active means non-archived. | Limit | Free | Starter | Pro | Enterprise | | ----------------- | ---- | ------- | --- | ---------- | | Active briefings | 0 | 2 | 5 | unlimited | | Rows per briefing | 0 | 4 | 8 | unlimited | | Items per row | 0 | 4 | 6 | unlimited | A source group counts toward the **items-per-row** budget by the number of sources inside it, not as one item — this matches how the briefing renders the group's child charts side-by-side. ## Why Briefings vs. Pulses? Pulses are the heartbeat — frequent, single-source, optimised for "is anything moving?". Briefings are the monthly retrospective — wide-angle, cross-source, optimised for "what's the overall picture and what should we do about it?". They share data (Briefings reuse the latest Pulse output for each item) but solve different jobs. # Briefing rows Source: https://docs.chartcastr.com/analysis/briefings/rows How briefing rows and row items work — what counts toward your per-row item budget, how source groups expand, and how rows are reordered. Rows are the unit of cross-source AI analysis inside a briefing. Each row holds one or more **row items** (a Source or a Source Group), and the AI writes commentary that synthesises just the items in that row. The page-level [Overall review](/analysis/briefings/overall-review) then synthesises across all rows. ## Row items A row item is a pointer to an existing thing in your workspace: | Kind | What gets pulled in | | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Source** | The latest chart image + AI short / long summary from that source's most recent Pulse run. | | **Source group** | The latest cross-source meta-analysis run for that group, including its representative chart and the per-child summaries. | Briefings never re-fetch data themselves. They reuse whatever the latest Pulse / Source-group analysis produced — so freshness depends on your Pulse cadence. If a source hasn't run recently, the row item shows "no recent data" and the AI commentary notes the gap. ## Item budget per row Each plan caps how many items can sit inside a single row: | Tier | Items per row | | ---------- | ------------- | | Free | 0 | | Starter | 4 | | Pro | 6 | | Enterprise | unlimited | ### How source groups count A source group does **not** count as one item — it counts as the **number of sources inside it**. The composer expands the group's child charts visually, so a group with 3 sources fills 3 of your row's item slots. If a source group is too big to fit into a row, the composer surfaces an inline "this would exceed your row's item budget" message before you confirm. Either split the group or move some items to another row. ## Row titles Rows have two titles: * **`title`** — what you typed. When set, this is what the user sees and it stays put. * **`aiTitle`** — a 2–5 word title generated by Haiku on every save, based on the row's items. Shown when `title` is empty. The composer falls back to `title ?? aiTitle ?? "Untitled row"`. If you've manually edited the title, the row is locked (`titleLockedByUser`) and the AI no longer overwrites it. You can choose **Reset to AI title** from the row menu to release the lock. The same pattern applies at the briefing level — `Briefing.name` vs. `Briefing.aiTitle`. Both regenerate in a single batched AI call on save. ## Reordering Rows and items reorder via arrow-up / arrow-down buttons on each card. There's no drag-and-drop in v1 — given the small numbers (8 rows × 6 items), the keyboard / click affordance was the simpler ship. Reordering only changes the row's `position` field — it does **not** retrigger AI analysis. Order only matters for how the briefing renders (composer, PDF) and for the cache hash that decides whether a row needs re-analysis on next save. ## When a row's analysis is reused Each row stores an `aiInputsHash` — a hash of its sorted item refs + their latest Pulse content IDs + the row title. On save, the orchestrator recomputes the hash: * **Hash matches** → the prior row commentary is reused. No LLM call, no token spend. The row gets a new `BriefingRowContent` row pointing back at the prior one via `aiReusedFromBriefingContentId`. * **Hash differs** → the row is re-analysed from scratch. This is why adding a brand-new row is cheap (only that row runs), and why renaming a row title or moving an item between rows triggers a re-analysis on the affected rows. ## Failure handling If a single row's AI commentary fails, the run does **not** abort. The failed row's `BriefingRowContent` is written with `aiError` set, a warning is appended to the run, and the orchestrator continues. The run is marked `SUCCESS` as long as at least one row produced commentary AND the overall summary call succeeded. The composer surfaces failed rows with a "row failed — retry" affordance on the snapshot detail page. # Save & commit Source: https://docs.chartcastr.com/analysis/briefings/save-and-commit Why briefings use an explicit save model, how AI regeneration works on commit, and why row edits are blocked while a commit is in flight. Briefings use an **explicit save** model. Editing rows, adding items, or renaming things only mutates the draft state on the server — they do **not** call the AI. The AI work happens in one batch when you press **Save**. ## Why explicit save? The alternative — debounced auto-regen — was rejected because: * Each save runs N row-analysis calls + 1 overall summary call. Auto-regen on every keystroke would burn tokens on edits the user is still composing. * Briefings are monthly. There's no "live dashboard" UX expectation; a deliberate commit step matches the cadence. * It makes the cost story predictable: one bounded burst per save, no surprises. ## What happens on save When you press Save, the client calls `commitAndRegenerateBriefing(id)`. The server: 1. Creates a new `BriefingContent` row with `status = IN_PROGRESS`, `triggerType = MANUAL`. 2. Snapshots the briefing's row + item composition into `BriefingContent.briefingSnapshot` (so the run is reproducible even if rows change later). 3. **Title pre-step:** if the briefing or any row has unlocked titles AND the title-input hash has changed, makes one batched Haiku call for all titles at once. 4. **Per-row commentary** in parallel (bounded to 3 in flight): * Recompute the row's `aiInputsHash`. * If it matches the row's existing hash, reuse the prior commentary (no LLM call). * Otherwise, fetch the row's items' latest Pulse output and call `generateBriefingRowAnalysis`. 5. **Overall review:** after all rows complete, run `generateBriefingOverallSummary` over the row outputs + item short summaries. 6. Set `BriefingContent.status = SUCCESS`, write `aggregateTokenUsage`, end the run. The mutation returns immediately with the new `BriefingContent.id`. The composer polls `getBriefing` every 2 seconds until status leaves `IN_PROGRESS`. No PDF is rendered and no destination is contacted on a save. PDF and delivery only run on a [snapshot](/analysis/briefings/snapshots). ## Why row edits are blocked while a commit is in flight While a `BriefingContent` is `IN_PROGRESS` for a briefing, every `mutateBriefingRow` call is rejected with `BRIEFING_COMMIT_IN_PROGRESS`. The composer disables the row-edit affordances (drag handles, item picker, title fields) for the same reason. The lock exists because: * The snapshot was frozen at commit start. Downstream row analyses run against that frozen view. * Allowing edits during the run would silently invalidate the row hashes and produce stale-on-arrival results. * A typical commit takes \<30 seconds. A short read-only window is a clearer UX than letting writes race. The lock is **per-briefing only** — other briefings remain freely editable, and any unrelated mutation (sources, connections, settings) is unaffected. ### Stale runs If a commit somehow gets stuck (server crash, network partition), a 30-minute sweeper transitions abandoned `IN_PROGRESS` runs to `FAILED` so the briefing isn't permanently locked. ## The `needsCommit` flag `Briefing.needsCommit` is the single source of truth for "this briefing has uncommitted changes". The server computes it from row-level `aiInputsHash` mismatches — **don't** derive it on the client from `updatedAt` timestamps. The composer's "Unsaved changes" badge reads this field directly. `Send Snapshot` is disabled when: * `needsCommit === true` — there's nothing fresh to send, * `isCommitting === true` — a save is in flight, or * The monthly throttle says next-eligible-date is in the future. ## What changes trigger AI work? | Edit | Title regen? | Row commentary regen? | Overall review regen? | | -------------------------- | ------------------------- | --------------------- | --------------------- | | Add a row | ✅ (new row needs a title) | ✅ (new row only) | ✅ (always) | | Add an item to a row | ✅ (row title may shift) | ✅ (just that row) | ✅ | | Remove an item | ✅ | ✅ (just that row) | ✅ | | Reorder items within a row | ❌ | ❌ | ✅ | | Reorder rows | ❌ | ❌ | ✅ | | Type a row title | ❌ | ❌ | ✅ | | Edit briefing description | ✅ | ❌ | ✅ | | Reset to AI title | ✅ | ❌ | ✅ | The overall review **always** runs because it's a single small call and depends on every row's output. # Snapshots & delivery Source: https://docs.chartcastr.com/analysis/briefings/snapshots How Chartcastr renders monthly briefing PDFs, the once-per-calendar-month throttle, and destination delivery. A **snapshot** is a frozen, multi-page PDF render of your briefing at a point in time, plus the act of delivering it to your destination. Snapshots are throttled to **once per calendar month** per briefing. ## When snapshots run | Trigger | Source | Throttle? | | ------------------------ | ----------------------------------------------------------------------------------------------- | --------- | | Scheduled | The monthly cron, fired by the briefing's connection at the day-of-month + time you configured. | Yes. | | Manual ("Send Snapshot") | The button in the composer or list page. | Yes. | | Manual override | Org admins only — bypasses the monthly throttle for support / failed-delivery retries. | No. | If a scheduled or manual run hits the throttle, the orchestrator writes a `BriefingContent` with `status = UNCHANGED` and `runWarnings = [{ code: 'THROTTLED_MONTHLY' }]`, then exits without calling the AI or rendering a PDF. "Calendar month" is computed in your **organisation's timezone**, not UTC. A briefing scheduled for the 1st of the month will fire on your local 1st, and `lastSnapshotAt` is compared against the start of that local month. ## Schedule shape The briefing settings page exposes a structured form, not a cron textarea: * **Day of month**: 1–28 (avoids the 29/30/31 edge cases). * **Hour**: 0–23, in your org timezone. * **Minute**: 0–59. The server materialises this to a cron expression internally — the UI never sees one. ## What's in the PDF The PDF is rendered server-side with `@react-pdf/renderer` (Bun-compatible, no headless browser). Layout: | Page | Contents | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **1 — Cover** | Briefing name, period label (e.g. "April 2026"), generated timestamp, organisation name, description, brand mark. | | **2 — Big Picture** | The overall review — `aiSummaryLong` body + highlight bullets. Placed up-front. | | **3+ — Per-row sections** | For each row: title, item grid (chart image + name + short summary, 2 per row), then the cross-analysis commentary + highlights. | | **Last — Appendix** | Per-item full long summaries (anything that didn't fit above), and a data-freshness table showing each item's `latest.generatedAt` vs. fresh / stale. | The PDF is uploaded to R2 and linked from `BriefingContent.pdfUrl` so it can be re-downloaded from the snapshot history page even after delivery. ## Delivery Briefings are delivered to your configured [destination](/integrations/destinations). The cover message includes the briefing name, period label, the overall short summary, and a link to view the snapshot online. The PDF is attached to the message wherever the destination supports attachments; if the file is too large for the destination, Chartcastr falls back to a download link instead. The deliverable is consistent across destinations — only the wrapping format differs. ## Snapshot history Every run — successful, throttled, failed — writes a `BriefingContent` row. The `/admin/briefings/[id]/snapshots` page lists them, ordered newest-first. By default the list filters to `status = SUCCESS` and `pdfUrl IS NOT NULL`; toggle to show all. Each row records: * Completion date, status, trigger type (Scheduled / Manual) * Token usage breakdown (titles + rows + overall) * PDF download link * A view of the frozen `briefingSnapshot` so the snapshot detail page can re-render the briefing exactly as it was delivered, even if you've since changed the live composition. ## Failure modes | Code | Cause | What it means | | ----------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `THROTTLED_MONTHLY` | A run for the same briefing already completed this calendar month. | Run exits early. No AI, no PDF. Use the admin override to bypass. | | `BRIEFING_COMMIT_IN_PROGRESS` | A save is already in flight. | Wait for the in-flight run to finish. | | `PLAN_UPGRADE_REQUIRED` | The org's plan dropped below paid. | Read access still works; mutations and new snapshots are blocked. Existing scheduled connections move to `DEGRADED`. | A run is `SUCCESS` when at least one row produced commentary AND the overall summary call succeeded. A row that failed individually is recorded with `aiError` set and surfaces on the snapshot detail page as a per-row "retry" affordance — it does not block the rest of the briefing from being delivered. # Briefings use cases Source: https://docs.chartcastr.com/analysis/briefings/use-cases How teams actually use Chartcastr Briefings — accelerated client reporting, board deck prep, pitch deck prep, and the monthly all-hands recap. A [Briefing](/analysis/briefings/overview) is a single PDF that synthesises across every source you care about, with cross-source AI commentary and a page-level overall review, delivered on a once-per-calendar-month cadence. That shape fits a handful of jobs particularly well. Each section below has a short summary plus a deeper write-up on the [Chartcastr blog](https://chartcastr.com/blog) — half release note, half playbook for the use case. ## Accelerated client reporting For agencies that build the same monthly client report by hand. One Briefing per client, rows for each theme (Acquisition, Retention, Finance, etc.), AI commentary already written, PDF auto-delivered on the 1st. The before / after is stark: 4–6 hours per client per month becomes a one-time setup. Reporting that lagged the data by a week now fires automatically when the month closes. Accelerated Client Reporting with Chartcastr Briefings — agency setup walkthrough, the time-cost math, and where to start. ## Board deck asset prep For founders and finance leads who rebuild the appendix every board cycle. The Briefing becomes the living appendix — Finance, Growth, Retention, Acquisition, Product as rows — and the [overall review](/analysis/briefings/overall-review) becomes the first draft of the CEO's "what happened this month" page. Stable structure, fresh data, monthly cadence, polished output. That's exactly what a board deck appendix needs. Stop Rebuilding the Board Deck — how Briefings hold up across 12 board cycles, and what the PDF looks like when it lands in a board pack. ## Pitch deck prep For founders who are mid-fundraise and tired of patching stale charts into the deck. A "metrics for investors" Briefing lives next to the deck — not inside it. The deck stays deliberate; the Briefing carries the freshness load. Trigger a manual snapshot before any investor call. The cover summary and overall review give the investor enough context to come prepared with sharper questions. Pitch Deck Prep: A Briefing for Every Investor Conversation — the deck-vs-metrics-pack split, the before-call workflow, and what investors actually want. ## All-hands progress reports For leadership teams that assemble the monthly all-hands recap from scratch every cycle. One row per function — Product, Go-to-market, Customer Success, Engineering, People — and the AI cross-analysis surfaces the themes leadership would otherwise hunt for across six different dashboards. The PDF lands the morning of the all-hands. Leadership reads it once, edits the framing, walks into the meeting an hour later. The All-Hands Progress Report, Written for You — the section structure, the morning-of workflow, and what leadership keeps doing vs. stops doing. ## Pick the one that fits and start there Don't roll Briefings out across every workflow at once. Pick one job — the one that's most painful right now — and build a single briefing for it. Run a manual snapshot before the next reporting cycle. Compare the output to what you'd have built by hand. By cycle two you'll know the shape, and the other use cases will feel like obvious next steps. What a briefing is, plan limits, and how rows and items compose. Tour of the list, composer, settings, and snapshot history. # Chat actions Source: https://docs.chartcastr.com/analysis/chat/actions Create connections, manage pulses, update source groups, and edit workspace configuration using natural language commands in Chartcastr AI chat. ## Overview The Chartcastr AI Chat isn't just for asking questions—it's a powerful tool for taking action. You can manage your connections, pulses, and configuration directly through natural language. ## Key Actions ### Creating Connections You can set up new connections by simply describing what you want to achieve. * *"Set up a new Google Sheets connection for my Marketing dashboard"* * *"Link the Sales tab from this spreadsheet to the #revenue Slack channel"* ### Managing Pulses Interact with your existing pulses without navigating through the dashboard. * *"Show me my latest pulses"* * *"When is the next pulse for the Product team scheduled?"* * *"Disable the Daily Revenue pulse for the weekend"* ### Bulk Updates with Source Groups Manage your sources at scale using Chat, including context assignments. * *"Group all my Shopify sources into a new 'Ecommerce' group"* * *"Add the 'Q1 Strategy' document as [External Context](/analysis/context/overview) to all sources in the Marketing group"* * *"Update all sources in the Sales group to use the same analysis template"* ### Configuration Edits Quickly modify your workspace settings and context. * *"Update the [User Notes](/analysis/context/user-notes) for my Slack Revenue connection to mention the Q4 promotion"* * *"Invite [sarah@company.com](mailto:sarah@company.com) to this workspace as an admin"* * *"Change the reporting timezone to EST for all my pulses"* ## Workflow Automation Chat can help you stitch together complex tasks into simple commands. For example: *"Create a new source group for all European sales data and set up a weekly Slack pulse to #emea-growth every Friday at 9am."* ## Feedback Loop When you ask Chat to perform an action, it will usually provide a confirmation or a draft of the changes. You can review and refine the action before it's finalized. * *"Looks good, go ahead"* * *"Wait, change the delivery time to 10am instead"* # Conversational data analysis Source: https://docs.chartcastr.com/analysis/chat/analysis Ask complex questions about your data in Chartcastr AI chat. The assistant uses external context, pulse history, and documents for deeper insights. ## Overview Chartcastr AI Chat provides a conversational interface for deep analysis of your data. It goes beyond simple snapshots, allowing you to ask complex questions that leverage the full [Context](/analysis/context/overview) of your workspace. ### Context Discovery The AI automatically discovers context from your [connected sources and documents](/analysis/context/overview) to make every interaction smarter. It doesn't just look at the numbers; it reads your strategy docs and metric definitions to explain *why* the numbers are changing. ## Context-Aware Analysis The power of Chat analysis comes from its ability to synthesize multiple information sources: ### Pulse and Connection Data Chat has direct access to your latest pulse data and connection history. * *"Why did revenue drop yesterday compared to the same day last week?"* * *"Which items are currently trending in our inventory?"* ### External Context Integration If you've linked [External Context](/analysis/context/overview) (like Google Docs or Sheets), Chat incorporates that information into its analysis. * *"Based on our Q1 Strategy document, how are we tracking against our growth goals?"* * *"Explain the latest revenue numbers in the context of our pricing update definitions in Sheets."* ### Comparing Data You can use Chat to compare performance across different sources or time periods. * *"Compare the conversion rate of our Facebook ads vs Google ads over the last 30 days."* * *"Show me how the new product launch in London compares to the Manchester launch."* ## Interactive Exploration Analysis in Chat is iterative. You can start with a broad question and drill down into specific details. 1. **Start Broad**: *"How was our performance last week?"* 2. **Drill Down**: *"Break down that revenue spike by category."* 3. **Analyze Root Cause**: *"Was that increase driven by new customers or existing ones?"* 4. **Get Recommendations**: *"What should we focus on next week to maintain this momentum?"* ## Visualizing Insights While Chat is primarily text-based, it can help you prepare data for visualization. * *"Summarize these findings into a list of bullet points for my weekly report."* * *"Format the revenue comparison as a table."* ## Privacy and Data Security Chat analysis respects all your existing permissions and data security settings. It only analyzes data that you have explicit access to within the workspace. # Chat follow-ups in Slack and Teams Source: https://docs.chartcastr.com/analysis/chat/followups Tag @chartcastr in a Slack or Teams pulse thread to ask follow-up questions about your charts. Get context-aware answers without leaving the channel. ## Overview Chat Follow-ups let you ask questions about your charts directly within Slack or Microsoft Teams. By tagging `@chartcastr` in a pulse thread or channel, you can get contextual answers about your data without leaving your conversation. ## How It Works When you tag `@chartcastr` in a channel where the bot is present, it analyzes the context of your message and provides an intelligent response inline. ### Thread Context Chartcastr is context-aware. When you tag it within a thread attached to a Pulse notification: * It knows **which pulse** you're asking about * It understands **the specific chart data** in that pulse * It has access to [External Context and User Notes](/analysis/context/overview) linked to that source * It remembers **the conversation history** in the thread **Example:** ``` [Chartcastr Pulse in #sales-reports] 📊 Weekly Revenue: $125,000 (+12%) AI Summary: Revenue exceeded targets driven by enterprise upgrades... --- Thread --- You: @chartcastr Which specific customers drove the increase? Chartcastr: The increase was primarily driven by 3 enterprise accounts upgrading to annual plans: Acme Corp (+$15K), TechStart (+$12K), and Global Industries (+$8K). These were all Q4 contract renewals that moved from monthly to annual billing. You: @chartcastr How does this compare to last quarter? Chartcastr: Q4 upgrades are tracking 23% higher than Q3. Last quarter had 5 major upgrades totaling $28K, while this quarter already has 8 upgrades totaling $45K with 3 weeks remaining. ``` ### Channel Questions You can also ask general questions in channels where Chartcastr is a member: ``` You: @chartcastr What's our current MRR? Chartcastr: Your current MRR is $487,500 as of today. This is up 2.3% from last month. The main growth driver has been the new Starter plan tier which contributed $18K in new revenue. You: @chartcastr Show me all active pulses Chartcastr: You have 12 active pulses: • Weekly Revenue → #exec-reports (Mondays 9am) • Daily Active Users → #product-team (Daily 8am) • Campaign Performance → #marketing (Fridays 4pm) ...and 9 more. View all in your dashboard: https://chartcastr.com/admin/pulses ``` ## Supported Platforms Full support for tagging @chartcastr in: * Pulse threads for contextual follow-ups * Channels where Chartcastr is a member * Direct messages to the Chartcastr app The bot understands thread context and can reference the specific pulse data when replying. Learn more about setting up Slack **Coming Soon** — Microsoft Teams follow-up support is in development alongside the Teams integration. When launched, you'll be able to: * Tag @chartcastr in Teams channels * Ask follow-ups in pulse threads * Get contextual answers about your data View Teams integration status ## What You Can Ask ### In Pulse Threads * "What caused this spike?" * "Break down the top contributors" * "Which segments performed best?" * "Show me the underlying data" * "How does this compare to last week?" * "What's the MoM trend?" * "Compare this to Q3 performance" * "How are we tracking against goal?" * "Explain what this metric means" * "Why is this important?" * "What should we do about this?" * "Summarize the key takeaways" * "Who should I notify about this?" * "Should we schedule a follow-up meeting?" * "Create a task to investigate the drop" * "Alert the team if this drops below X" ### General Questions * "What's the status of \[source/connection]?" * "Show me my active pulses" * "When is the next pulse sending?" * "Help me create a new connection" * "Why didn't my last pulse send?" * "What's our \[metric] for \[time period]?" ## Best Practices When asking about a specific pulse, reply in the pulse thread. The AI automatically knows which chart you're referring to. Good: "@chartcastr What was our revenue last Tuesday?" Vague: "@chartcastr show me numbers" The AI maintains conversation history in threads. You can reference previous answers: "@chartcastr Expand on that last point about churn" Request specific formats for better readability: * "@chartcastr Show this as a table" * "@chartcastr Give me bullet points" * "@chartcastr Keep it brief" ## Privacy & Thread Access * Only users who can see the pulse can tag @chartcastr in the thread * The bot respects your workspace permissions * External context is only used if the source has linked documents * Thread conversations are stored for context but not shared across workspaces ## Limitations Follow-up messages count toward your AI Chat daily limits based on your plan: | Plan | Messages Per Day | | :--------- | :--------------- | | Free | 2 | | Starter | 10 | | Pro | 100 | | Enterprise | Unlimited | Chartcastr only responds when tagged. It won't proactively message channels or start conversations. The AI can only access data and connections within your Chartcastr workspace. ## Troubleshooting * Ensure @chartcastr is invited to the channel * Check that the bot is online in your workspace * Verify you haven't hit your daily message limit * Try re-inviting the bot if issues persist * Make sure you're in a pulse thread (not just a regular channel message) * Be specific about which source or metric you're asking about * The bot may ask clarifying questions if context is unclear * The AI can only access sources and connections you have permission to see * External context documents must be properly linked to the source * Some historical data may not be available depending on retention settings ## Example Workflows ### Weekly Standup ``` [Monday 9am - Weekly Revenue Pulse in #sales] You: @chartcastr What's the breakdown by product tier? Chartcastr: Enterprise: $85K (68%), Pro: $28K (22%), Starter: $12K (10%) You: @chartcastr Any concerning churn signals? Chartcastr: No immediate concerns. Churn is at 2.1%, below the 3% threshold. However, 2 enterprise customers have contracts expiring this month worth $24K total. I recommend proactive outreach. You: @chartcastr Draft an alert for the team Chartcastr: 📋 Draft alert: "🎯 Weekly Revenue: $125K (+12%) ⚠️ Action needed: 2 enterprise renewals at risk ($24K) ✅ Next steps: Review expiring contracts" Reply "send" to post this to the channel. ``` ### Incident Response ``` [Alert Pulse in #engineering] 📉 Error Rate Spike: 5.2% (normal: <1%) You: @chartcastr When did this start? Chartcastr: Error rate began increasing at 14:32 UTC, approximately 45 minutes ago. First spike coincided with deployment #2847. You: @chartcastr Which endpoints are affected? Chartcastr: Top 3 affected endpoints: 1. /api/v2/checkout (2.1% error rate) 2. /api/v2/payments (1.8% error rate) 3. /webhooks/stripe (0.9% error rate) You: @chartcastr Is this related to the payment service issues? Chartcastr: Based on the error patterns and your linked incident response doc, this matches the symptoms of the payment gateway timeout issue. The checkout and payment endpoint errors both involve 504 gateway timeouts. ``` ## Next Steps Learn how to interact with the bot directly in Slack channels. Connect Slack to start using follow-ups. # AI chat overview Source: https://docs.chartcastr.com/analysis/chat/overview Explore what Chartcastr AI chat can do — manage automations, analyze data, ask follow-up questions, and take actions using your workspace context. The Chartcastr AI Chat is an intelligent assistant designed to help you manage your automations, explore your data, and get answers about your workspace. It is context-aware, meaning it understands your connected sources, destinations, and existing automations. ### Smart Analysis through Context Chat is uniquely powerful because it discovers and leverages your [Context](/analysis/context/overview). When you link Google Docs, Sheets, or add User Notes, the AI assistant reads this background information to provide significantly smarter and more relevant analysis of your data. Start here to learn about the core capabilities of Chartcastr AI Chat. Tag @chartcastr in Slack or Teams for contextual follow-up questions about pulses. Create connections, manage pulses, and update your configuration through chat. Deep-dive into your data, compare sources, and leverage external context. # Confluence context (coming soon) Source: https://docs.chartcastr.com/analysis/context/confluence Planned integration to link Confluence pages as external context for Chartcastr AI analysis. Ideal for technical docs, runbooks, and project specs. **State**: Coming Soon — Confluence integration is on our roadmap. ## Overview We are planning to add support for Confluence pages to provide technical and operational context for your data. Ideal for: * Technical documentation * Product specifications * Team documentation * Project runbooks ## Planned Features * **Space Integration**: Link entire Confluence spaces or specific pages to Source Groups. * **Deep Indexing**: AI analysis will leverage your internal documentation to explain data anomalies based on technical specs or project timelines. * **Automatic Updates**: When you update a Confluence page, Chartcastr will automatically reflect those changes in future pulse analyses. ## Request This Feature If your team uses Confluence and would benefit from this integration, let us know! User feedback helps us prioritize our roadmap. Tell us how you'd use Confluence context in your pulses. # Google Docs as context Source: https://docs.chartcastr.com/analysis/context/google-docs Link Google Docs strategy documents, planning memos, and playbooks to your Chartcastr sources so AI summaries reflect your business goals. ## Overview Extract content from Google Docs and use it to provide business context for your AI analysis. Ideal for: * Strategy documents and planning memos * Project requirements and specifications * Company playbooks and methodologies * Quarterly planning documents ## How It Works 1. **Link Documents**: Connect documents from Google Drive to a Source or Source Group. 2. **AI Reads Context**: When generating pulse summaries, the AI reads and incorporates the full text of the linked documents. 3. **Better Insights**: Summaries are more informed by your business goals and strategies. ## Document Limits Each Source or Source Group can have up to **3 external context documents** linked. | Plan | Documents per Source/Group | | :------------- | :---------------------------------------------------------------------------------------- | | **All Plans** | 3 | | **Need More?** | [Contact Us](mailto:support@chartcastr.com?subject=External%20Context%20Limit%20Increase) | Need more than 3 documents per source? Contact us at [support@chartcastr.com](mailto:support@chartcastr.com) to discuss your requirements. ## Linking Google Docs ### From Settings You can manage all your linked external documents in the Context section of your settings. 1. Go to [Settings](https://chartcastr.com/admin/settings). 2. Click **Manage** on the **Context** card. 3. Use the **External Documents** view to see and manage linked files. 4. Click **Link Context File** to add a new document. 5. Select **Single Source** or **Source Group** as your target. 6. Search and select a document from Google Drive. 7. Click **Link Context File** to save. ### From a Source Page 1. Navigate to a Source's detail page. 2. Find the **External Context Documents** section. 3. Click **+ Add**. 4. Follow the same process as above (Source will be pre-selected). ## Best Practices Link documents that directly relate to the data being analyzed. A project strategy document works better than a general company overview. If multiple sources share the same business context (e.g., all marketing metrics), link the document to a Source Group rather than each individual source. While AI can read long documents, keeping your context documents focused on key facts and strategies will yield the best results in pulse summaries. ## Troubleshooting Each target (Source or Source Group) can have up to 3 documents. Remove existing documents or contact us for increased limits. Ensure you've connected your Google account and the document is accessible. Try searching by name or scroll through recent files. External context is read at the time of pulse generation. Changes to linked documents will be reflected in the next pulse. # Google Sheets as context Source: https://docs.chartcastr.com/analysis/context/google-sheets Connect specific Google Sheets tabs as external context for Chartcastr AI analysis. Perfect for metric definitions, benchmarks, and lookup tables. ## Overview Connect individual sheet tabs from Google Sheets to your Sources or Source Groups. Perfect for: * Metric definition spreadsheets * Lookup tables and reference data * Historical benchmarks * Calculated metrics documentation **Note**: You select a specific sheet tab, not the entire spreadsheet. This keeps the AI focused on relevant information. ## How It Works 1. **Link Documents**: Connect specific sheet tabs from your Google Sheets to a Source or Source Group. 2. **AI Reads Context**: When generating pulse summaries, the AI reads and incorporates the data from these sheets. 3. **Better Insights**: Summaries are more relevant because the AI understands your metrics and reference data. ## Document Limits Each Source or Source Group can have up to **3 external context documents** linked. | Plan | Documents per Source/Group | | :------------- | :---------------------------------------------------------------------------------------- | | **All Plans** | 3 | | **Need More?** | [Contact Us](mailto:support@chartcastr.com?subject=External%20Context%20Limit%20Increase) | Need more than 3 documents per source? Contact us at [support@chartcastr.com](mailto:support@chartcastr.com) to discuss your requirements. ## Linking Google Sheets ### From Settings You can manage all your linked external documents in the Context section of your settings. 1. Go to [Settings](https://chartcastr.com/admin/settings). 2. Click **Manage** on the **Context** card. 3. Use the **External Documents** view to see and manage linked files. 4. Click **Link Context File** to add a new document. 5. Select **Single Source** or **Source Group** as your target. 6. Search and select a file from Google Drive. 7. Select the specific sheet tab you want to use. 8. Click **Link Context File** to save. ### From a Source Page 1. Navigate to a Source's detail page. 2. Find the **External Context Documents** section. 3. Click **+ Add**. 4. Follow the same process as above (Source will be pre-selected). ## Best Practices Link documents that directly relate to the data being analyzed. A glossary of metric definitions works better than a general company overview. If multiple sources share the same business context (e.g., all marketing metrics), link the context document to a Source Group rather than each individual source. Choose the specific tab that contains relevant definitions or context. This ensures the AI receives focused, pertinent information. ## Troubleshooting Each target (Source or Source Group) can have up to 3 documents. Remove existing documents or contact us for increased limits. Ensure you've connected your Google account and the file is accessible. Try searching by name or scroll through recent files. External context is read at the time of pulse generation. Changes to linked documents will be reflected in the next pulse. # Granola meeting notes as context Source: https://docs.chartcastr.com/analysis/context/granola Link Granola meeting notes to Chartcastr sources so AI pulse summaries correlate metric changes with recent decisions and action items. **State**: Available on all plans. Requires a Granola **Business** or **Enterprise** plan for API access. ## Overview Link Granola meeting notes to your Chartcastr Sources to provide meeting context for your automated pulses. This is perfect for: * Correlating metric changes with recent meetings and decisions * Adding meeting summaries as context for chart analysis * Understanding the "why" behind data trends using meeting notes ## How It Works 1. **Connect Granola**: Enter your Granola API key in the Integrations settings. 2. **Link Context**: From any Source details page, click "Add Source Context" and select Granola. 3. **Select Notes**: Browse and select meeting notes to use as context for your charts. 4. **AI Analysis**: Our AI automatically uses the meeting summaries to provide deeper insights into your pulse summaries, connecting your live data to your meeting context. ## Setup Open the **Granola desktop app**, go to **Settings → API → Create new key**, and generate a key. Granola API key settings screen

Granola offers two key types — either works with Chartcastr: | Key Type | Scope | Plan Required | | ---------------------- | ----------------------------------------------------------------------------------- | ----------------------- | | **Personal API key** | Your own notes, notes shared with you, and notes in private folders shared with you | Business or Enterprise | | **Enterprise API key** | All notes in the Team space (org-wide, excludes private notes/folders) | Enterprise only (admin) | **Which key should I use?** Use a **Personal API key** if you want to attach your own meeting notes as context. Use an **Enterprise API key** if a workspace admin wants to provide org-wide meeting context across all team members' notes. On Enterprise plans, workspace admins can control whether members can create Personal API keys via the **"Allow personal API keys"** toggle in **Settings → Workspace**. In Chartcastr, go to **Settings** → **Source Integrations** and find the **Granola** card. Enter your API key and click **Test & Connect**. From any Source or Source Group detail page, click **Add Source Context**, select **Granola**, and browse your meeting notes. Select the notes relevant to the data you're tracking. ## What Gets Cached When you attach a Granola meeting note, Chartcastr caches the following information for AI analysis: * **Meeting title** and date/time * **Attendees** (names and emails) * **AI-generated summary** (in markdown format) * **Folder membership** for organizational context Full transcripts are not cached to keep token usage efficient. The AI summary provides the most relevant context in a compact form. ## Benefits By linking Granola meeting notes, your AI-generated summaries will understand the "why" behind your data: * Correlate metric spikes with decisions made in recent meetings * Include meeting context in your daily or weekly pulses * Get smarter answers to follow-up questions in Slack based on your meeting history ## Access Scope What notes you can browse in Chartcastr depends on which API key type you use: | Key Type | What You Can Access | | ---------------------- | ---------------------------------------------------------------------------------------------------- | | **Personal API key** | Notes you own, notes shared with you, notes in private folders shared with you | | **Enterprise API key** | All notes in the Team space (everything workspace members can read, excluding private notes/folders) | If your organization has multiple Granola workspaces, you'll need a separate API key per workspace. ## Rate Limits Granola enforces rate limits per user (Personal) or per workspace (Enterprise): | Metric | Value | | -------------- | ------------------------------ | | Burst capacity | 25 requests | | Time window | 5 seconds | | Sustained rate | 5 requests/second (300/minute) | Chartcastr respects these limits when browsing and fetching notes. ## FAQ A **Business** or **Enterprise** plan. Personal API keys are available on both. Enterprise API keys require the Enterprise plan and must be created by a workspace admin. Granola also offers an MCP (Model Context Protocol) integration for conversational AI tools like Claude and ChatGPT. The MCP uses browser-based OAuth and is designed for interactive chat. For Chartcastr's automated context enrichment, the API key approach is the right fit since it runs in the background without user interaction. Not yet — Granola's webhook support is on their roadmap. Currently, Chartcastr fetches note content when you attach a note as context. # Notion as context Source: https://docs.chartcastr.com/analysis/context/notion Connect Notion pages and databases as external context for Chartcastr AI. Correlate data trends with project milestones and team documentation. **State**: Available on all plans. ## Overview Link Notion pages and databases to your Chartcastr Sources to provide deep qualitative context for your automated pulses. This is perfect for: * Team wikis and knowledge bases * Project documentation * Process documentation * Research and analysis notes ## How It Works 1. **Connect Notion**: Authenticate your Notion workspace using the Integrations settings. 2. **Link Context**: From any Source details page, click "Add Source Context" and select Notion. 3. **Select Pages**: Choose specific pages or database entries to use as context for your charts. 4. **AI Analysis**: Our AI automatically indexes these pages to provide deeper insights into your pulse summaries, connecting your live data to your documentation. ## Benefits By linking Notion, your AI-generated summaries will understand the "why" behind your data: * Correlate metric spikes with project milestones documented in Notion. * Include process context in your daily or weekly pulses. * Get smarter answers to follow-up questions in Slack based on your internal documentation. ## Permissions & Troubleshooting ### Initial Setup On your initial signup, Notion requires you to explicitly select the specific files, pages, or workspace tree that Chartcastr has permission to access. While selecting a parent page is expected to grant access to all its children, this inheritance can sometimes be inconsistent. If new files or pages don't show up in Chartcastr, follow the instructions below to manually grant access. ### Manually Adding Connections If new files or pages don't show up automatically, you can manually add the Chartcastr connection to any Notion page (including parent pages to grant access to an entire tree). 1. **Open the Page Menu**: Click the three dots `...` in the top right corner of the Notion page. 2. **Add Connection**: Scroll down to "Connect to" or "Add connections". 3. **Find Chartcastr**: Search for "Chartcastr" and select it. 4. **Confirm**: Once added, the page and its children will be accessible to Chartcastr. Step 1: Click the connection button

Adding a connection to a **parent page** will automatically grant Chartcastr access to all its sub-pages! ## Rich Link Previews When you paste a Chartcastr URL into a Notion page, Notion can automatically unfurl it into a rich preview showing connection details, chart images, AI summaries, and status — right inline in your document. ### Supported URLs Any URL matching `chartcastr.com/admin/*` will be unfurled, including: * **Connection pages** — shows connection name, status, and configuration * **Source pages** — shows source details and linked integrations * **Job Run pages** — shows the chart image, AI summary, and run status ### Getting Started The first time you paste a Chartcastr link, Notion will prompt you to connect your Chartcastr account. Sign in and approve access — this is a one-time step. Paste any Chartcastr admin URL into a Notion page. Notion will automatically fetch a rich preview with chart images and metadata. Previews are fetched each time the page loads, so they always reflect the latest data from Chartcastr. **Availability**: Rich link previews require a **paid plan** (Starter, Pro, or Enterprise). ### Example Pasting a job run URL like `https://chartcastr.com/admin/connections/jobruns/abc123` will render an inline preview showing: * The chart image from the most recent run * AI-generated summary of the analysis * Run status and timestamp * Link back to the full Chartcastr dashboard ### Troubleshooting * **No preview appears**: Ensure you've authorized Chartcastr when prompted by Notion. If you dismissed the prompt, try pasting the link again. * **"Feature not available" error**: Rich link previews require a paid plan. Upgrade your plan in Chartcastr settings. * **Stale preview**: Notion caches previews — reload the Notion page to fetch the latest data. # OneDrive context (early access) Source: https://docs.chartcastr.com/analysis/context/onedrive Link OneDrive documents and Excel files as external context for Chartcastr AI analysis. Built for enterprise teams using Microsoft 365 file storage. **State**: Available on all plans. ## Overview OneDrive integration will allow enterprise teams to securely link corporate documents to their data analysis. Perfect for: * Corporate strategy documents * Compliance documentation * Team shared files * Executive reports ## Enterprise Ready Our OneDrive integration will focus on: * **Security**: Granular permission matching with your existing OneDrive setup. * **Large Document Support**: Indexing large PDFs and Word documents for high-level context. * **Organization-wide Context**: Easily apply shared context across all sources in your organization. ## Interested in OneDrive? If your organization uses OneDrive and you're interested in our enterprise context features, please reach out to our sales team. Discuss your enterprise documentation needs with us. # External context overview Source: https://docs.chartcastr.com/analysis/context/overview Add business context from Google Docs, Sheets, Notion, Granola, or user notes to improve the relevance and accuracy of Chartcastr AI analysis. Context is what makes AI analysis truly powerful. By providing background information about your data, you help the AI generate more relevant, accurate, and actionable insights. Chartcastr offers several ways to provide context. ## Available Now These integrations are currently available in the product for external context. Connect individual tabs for metric definitions and lookup data. Link strategy docs and planning memos for business context. Connect team wikis and project documentation. Link meeting notes so AI summaries understand decisions and follow-ups. Automatically use canvases from the destination Slack channel as analysis context. ## Planned These docs exist for roadmap visibility, but the integrations are not currently available in the context picker. Link corporate documents and executive reports from Microsoft 365. Link technical specs and team knowledge bases. ## User Notes Quickly add descriptions directly to your sources. Add custom descriptions directly to your sources or source groups. ## Next Steps View and manage all your linked documents and notes in one place. Organize your sources into groups to scale AI intelligence. # Slack Canvas as context Source: https://docs.chartcastr.com/analysis/context/slack-canvas Let Chartcastr automatically use Slack channel canvases as extra AI context for pulses sent into that channel. **State**: Available for Slack destinations after reconnecting the Slack app with the **`canvases:read`** permission. ## Overview Slack Canvas context gives Chartcastr access to canvases in the same Slack channel where a pulse is delivered. This is useful for: * Giving AI summaries channel-specific operating context * Letting follow-up answers reference runbooks, planning notes, and team docs already pinned to that channel * Keeping context automatic instead of manually mapping documents to every source ## How It Works 1. **Connect Slack as a destination** 2. **Reconnect once with `canvases:read` enabled** 3. **Send a connection to a Slack channel that has canvases** 4. **Chartcastr automatically makes those channel canvases available to the AI** There is **no manual mapping step**. If a connection sends to `#marketing`, the AI can inspect canvases from `#marketing`. If a different connection sends to `#finance`, the AI can inspect canvases from `#finance`. ## What Is Automatic When Slack Canvas permissions are enabled: * Initial pulse analysis can list canvases in the destination channel * The AI can read the most relevant canvas when its title looks useful * Slack follow-up replies in that pulse thread can use the same channel canvases for extra context Chartcastr does **not** require you to attach each canvas to a source or source group. ## Setup Connect your Slack workspace as a destination in Chartcastr. Go to the Slack integration detail page in **Settings → Destinations → Slack** and open the **Context** tab. If the integration does not show canvas access yet, click **Reconnect** and approve the **`canvases:read`** permission in Slack. Create or update a connection so the pulse is delivered to the Slack channel whose canvases should be available to the AI. ## Scope Slack Canvas context is **channel-scoped**: * A pulse sent to one Slack channel only gets canvases from that same channel * Private channel canvases are available only if the Chartcastr bot is in that private channel * If a channel has no canvases, the AI simply continues without them ## FAQ No. Slack Canvas context is automatic. Once the Slack integration has the right permission, canvases in the destination channel are available to the AI without per-source setup. No. Chartcastr exposes the channel canvases as available context, and the AI can inspect the relevant ones when needed. It does not need to read every canvas on every pulse. The Slack destination integration needs the **`canvases:read`** scope. Chartcastr also uses standard Slack file access already granted to the app to list and retrieve canvas content. Yes, if the Chartcastr bot has access to the private channel. If it is not a member, invite the bot first. # User notes Source: https://docs.chartcastr.com/analysis/context/user-notes Write free-text descriptions for your charts or source groups so the Chartcastr AI understands what the data represents and why it matters. ## Overview User Notes let you provide context about a specific chart or a collection of charts directly in the product. This context is included in pulse summaries and helps the AI understand what your data represents. User Notes are a quick way to add context, but for comprehensive business documentation, consider using External Context ([Google Sheets](/analysis/context/google-sheets), [Google Docs](/analysis/context/google-docs)) instead. Both can be mapped to [Single Sources](#assignment-options) or [Source Groups](/admin/sources/source-groups). ## What are User Notes? User Notes are a text field where you describe what a chart shows and why it matters. The AI includes this description when generating pulse summaries. **Example context:** ``` Weekly revenue from our SaaS product. This chart tracks MRR (Monthly Recurring Revenue) from all paid subscriptions. Spikes usually indicate annual billing cycles. Drops may reflect churn or downgrades. ``` ## How It Appears in Product When viewing a Source or [Source Group](/admin/sources/source-groups), you'll see: ``` User Notes Provide context about this chart to improve AI analysis quality. This context will be included in pulse summaries. Describe what this chart shows, e.g.: - "Weekly revenue from our SaaS product" - "Daily active users by platform" - "Ad spend vs conversions for Q4 campaign" ~0 / 500 tokens ``` ## Best Practices Good: "Weekly revenue from enterprise customers, excluding trials and refunds" Vague: "This is a revenue chart" Note patterns the AI should expect: * "Spikes on Mondays due to weekend batch processing" * "Zero values on holidays when offices are closed" * "Quarterly drops reflect planned maintenance windows" Clarify how metrics are calculated: * "LTV = Average revenue per user × Average customer lifetime" * "Active users = Unique logins in past 7 days" * "MRR includes all recurring subscriptions, excludes one-time fees" Help the AI understand significance: * "Target is 10% MoM growth" * "Alert threshold is 95% uptime" * "Below 5% is considered healthy churn" ## User Notes vs External Context | Feature | User Notes | External Context | | :---------------- | :---------------------------- | :-------------------------- | | **Setup** | Type directly in product | Link external documents | | **Maintenance** | Edit each source individually | Update document once | | **Collaboration** | Single user input | Team can edit documents | | **Length** | 500 tokens (\~375 words) | Full document content | | **Best for** | Quick descriptions | Comprehensive documentation | | **Sharing** | Sources & Groups supported | Sources & Groups supported | ## Assignment Options You can map User Notes at two levels: * **Single Source**: The note applies only to pulses from that specific source. * **Source Group**: The note applies to all sources within the group. This is ideal for describing general trends or shared goals across multiple charts. ## When to Use Each ### Use User Notes when: * You need a quick description * The context is specific to one chart or a small group * You're testing what context helps most * The explanation is short and simple ### Use External Context when: * You have existing strategy documents * Multiple sources share the same context * Context needs team collaboration * You want to maintain context in one place * The documentation is comprehensive **Consider External Context First** While User Notes are convenient, external documents are often better because: * They can be updated without editing each source * Teams can collaborate on documentation * Context stays in sync with actual business strategy * Easier to maintain as your business evolves Think of User Notes as a quick fix, External Context as the robust solution. ## Tips for Writing Great Context What does this chart measure? Be specific about metrics and time periods. Why should stakeholders care about this data? Connect it to business goals. What should the AI know about limitations or edge cases? What external factors might influence this data? (campaigns, seasonality, etc.) ## Example Contexts ### Revenue Chart ``` Weekly MRR (Monthly Recurring Revenue) from all active subscriptions. Excludes trials, refunds, and one-time setup fees. Spikes typically indicate annual plan conversions. Target growth is 10% MoM. Data updates every Monday morning after weekend batch processing. ``` ### User Activity ``` Daily active users (DAU) measured as unique logins in past 24 hours. Includes all platforms (web, iOS, Android). Weekend dip is normal. Major product releases usually cause 15-20% spike in following week. Baseline target is 10,000 DAU. ``` ### Campaign Performance ``` Q4 holiday campaign performance tracking ad spend vs attributed conversions. Includes Facebook, Google, and LinkedIn ads. ROAS target is 3.0x. Attribution window is 7-day click. Exclude December 24-26 from analysis due to holiday shipping cutoff. ``` ## Managing User Notes You can manage all sources and their notes in the context settings. 1. Navigate to the Source or [Source Group](/admin/sources/source-groups) detail page. 2. Find the **User Notes** section. 3. Click the text area and enter your description. 4. Changes are saved automatically. 5. New pulses will include the updated context. Changes to User Notes take effect on the next pulse generation. Existing pulses are not retroactively updated. ## Next Steps Add notes to one of your existing sources or groups Learn about linking external documents # AI analysis in pulses Source: https://docs.chartcastr.com/analysis/in-pulses Learn how Chartcastr generates small summaries and overall analyses inside pulse threads. Tips for improving accuracy with context documents. Analysis in Pulses allows you to get instant insights into your data directly within your communication channels. This feature provides structured summaries and actionable insights based on the data points captured in each pulse. ## How it Works When a Pulse is triggered, Chartcastr processes the underlying data through our AI analysis engine. If you have provided [Context](/analysis/context/overview), the AI incorporates your business knowledge into these insights. ### Small Summary The **Small Summary** is designed for quick consumption. It highlights the most critical changes or data points in a concise format, usually appearing as the lead-in to a pulse message in Slack or Microsoft Teams. * **Purpose**: At-a-glance status updates. * **Focus**: Key metrics and immediate changes. ### Overall Summary (within the thread) Within the pulse thread, Chartcastr provides an **Overall Summary**. This is a more comprehensive breakdown of the data, providing context on trends and highlighting anomalies that might require attention. * **Threaded analysis**: Keeps the conversation focused on specific data events. * **Context-aware**: Integrates linked documents and notes to explain the "why" behind the numbers. ## Getting Better Results The accuracy and relevance of Pulse analysis improve as you provide more context. 1. **Link Context Documents**: Add Google Docs, Notion pages, or Confluence spaces that describe your KPIs and business goals. 2. **Add User Notes**: Provide specific instructions or background info for particular source groups. 3. **Refine Source Groups**: Ensure your source groups are focused so the AI isn't overwhelmed with irrelevant data points. By refining these inputs, the AI becomes more aligned with your specific business logic, delivering insights that are more tailored to your team's needs. # Analysis features overview Source: https://docs.chartcastr.com/analysis/overview Explore Chartcastr AI analysis capabilities including external context, chat follow-ups, and intelligent summaries that make your charts actionable. The Analysis section covers all AI-powered features in Chartcastr that help you understand your data better. From intelligent summaries to conversational follow-ups, these tools make your charts more actionable and insightful. Provide business context through external documents or user notes to improve AI analysis. Deep-dive into your data and manage your workspace through conversation. ## Next Steps Learn how to add business context to your data. Ask questions about your pulses in Slack. # API Overview Source: https://docs.chartcastr.com/api/overview REST API for reading your Chartcastr sources and the latest pulse (chart image + AI summary + long analysis) for each source. Authenticated with an API key. ## Overview The Chartcastr Public API is a small, read-only REST surface for fetching your data sources and the latest [pulse](/admin/pulses) for each — the chart image, the short AI summary, and the long AI analysis. It's the same data you see in your dashboard, available programmatically for embeds, internal tools, AI agents, or any integration project that needs structured access to your delivered insights. For richer agent-style access (search, verify, deep links) use the [MCP integrations](/integrations/ai-tools) — Claude, ChatGPT, Cursor, and Codex all connect via API key. ## Base URL ``` https://public.api.chartcastr.com/v1 ``` The same routes are also reachable at `https://api.chartcastr.com/v1` (the production server uses both hosts). ## Authentication All requests require an API key passed in the `X-API-Key` header. ```bash theme={null} curl https://public.api.chartcastr.com/v1/sources \ -H "X-API-Key: sk_live_..." ``` Generate keys from **[Settings → API Keys](https://chartcastr.com/admin/settings/api-keys?create=true)** in your Chartcastr dashboard. Each key is scoped to a single account. Default expiry is 90 days. API keys are shown **once** at creation time. Store them securely — if you lose a key you must revoke and regenerate. ### Verify your key There's no dedicated `/ping` endpoint — instead, call `GET /v1/sources` to confirm a key works. Every successful response includes a `meta.account` object, so this single call doubles as both an access check and your first useful query. `200` means the key resolved; `401` means it's missing, invalid, or expired. Use this any time you want to confirm a key works before running a heavier integration flow. The response also tells you which account/email the key is bound to. **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": [ /* ... */ ] } ``` **Failure — 401** ```json theme={null} { "success": false, "error": "Invalid or expired API key" } ``` In CI/CD or onboarding flows, branch on the HTTP status: `200` → key works, `401` → prompt the user to regenerate, `429` → back off and retry. #### Common failure modes | Symptom | Likely cause | | ----------------------------------------- | ------------------------------------------------------- | | `401 Invalid or expired API key` | Key revoked, expired, or never existed | | `401 Authentication required` | `X-API-Key` header missing entirely | | `429 Too Many Requests` | More than 60 calls in the last minute on this key | | `200` but `meta.account.id` is unexpected | The key belongs to a different account than you thought | ## Response Shape Every successful response includes a `meta` object so you can confirm which account the key resolved to: ```json theme={null} { "meta": { "account": { "id": "acc_...", "email": "you@example.com" }, "requestedAt": "2026-05-08T10:31:48.000Z" }, "sources": [ ... ] } ``` ## Errors | Status | Meaning | | ------ | --------------------------------------------------- | | `401` | Missing or invalid `X-API-Key` | | `403` | Key valid but lacks the required scope | | `404` | Resource (source, pulse) not found for this account | | `429` | Rate limit exceeded | | `500` | Server error — retry with backoff | Error bodies follow the shape: ```json theme={null} { "success": false, "error": "No pulse found for this source" } ``` ## Rate Limits Public API endpoints are rate limited to **60 requests per minute** per API key. Each response includes the current window state in headers: | Header | Description | | ----------------------- | ----------------------------------------------- | | `X-RateLimit-Limit` | Maximum requests per window | | `X-RateLimit-Remaining` | Requests left in the current window | | `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets | ## OpenAPI Spec The full machine-readable spec is served at: ``` GET https://public.api.chartcastr.com/v1/openapi.yaml ``` You can paste this directly into Postman, Insomnia, or any OpenAPI-aware tool to generate a typed client. ## Endpoints List configured data sources. Fetch the latest pulse for a source. # Pulses Source: https://docs.chartcastr.com/api/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 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. ## 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 ` ${pulse.sourceName}

${pulse.aiSummaryShort}

Full analysis

${pulse.aiSummaryLong}

` ``` ## Next Steps Auth, rate limits, and the OpenAPI spec. Use the same key with Claude, ChatGPT, Cursor, or Codex via MCP. # Sources Source: https://docs.chartcastr.com/api/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 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" } ``` Results are capped at 10 sources, ordered by `updatedAt` descending. If you need a complete inventory, contact support — pagination is on the roadmap. ## 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 Pass any `id` from this list to the Pulses endpoint to get the chart, short summary, and long AI analysis. # What is Chartcastr? Source: https://docs.chartcastr.com/index Chartcastr automates chart delivery with AI summaries to Slack, Teams, and email. Connect data sources and get scheduled visual insights. Chartcastr Hero Light

## What is Chartcastr? Chartcastr enables you to automatically push charts and pivot tables from various data sources to messaging platforms like Slack and email. Share visual data insights and build up intelligence on growth lines of your business. Get started with Chartcastr in 5 minutes Browse available data sources and destinations Manage your connections and settings ## Key Features Schedule automatic delivery of charts from your data sources to your team's communication channels. Send charts to Slack or email. Configure multiple destinations for each chart. Set up hourly, daily, weekly, or custom schedules with timezone-aware delivery. ## How It Works Link your data source Link your source to destinations like Slack or email with custom settings Set when and how often to send your charts ## Popular Use Cases * **Daily Standups:**\ Share up-to-date KPI dashboards with your team every morning to keep everyone focused and aligned. * **Pulse Channels:**\ Automatically post analytics and updates to always-on channels like `#data-insights` or `#company-pulse`, so everyone can see trends in real time. * **Pattern Detection with AI:**\ Combine human review with AI-powered analysis—receive highlights or summaries pointing out patterns and outliers that might otherwise go unnoticed. ## Where [Briefings](/analysis/briefings/overview) shine Pulses are the heartbeat. Briefings are the monthly retrospective — a single PDF that synthesises across every source you care about, with cross-source AI commentary and an overall "big picture" review. A few of the use cases customers reach for first: * **Accelerated client reporting:**\ Replace the Monday-morning report build with a per-client briefing that auto-renders on the 1st of the month — every channel, every metric, one PDF, AI-written commentary already in place. * **Board deck asset prep:**\ Run a finance + growth + retention briefing the week before each board meeting. The PDF becomes the ready-made appendix, and the overall review becomes the first draft of your CEO update. * **Pitch deck prep:**\ Spin up a "metrics for investors" briefing that combines top-line growth, channel performance, and unit economics. Send a snapshot before every investor call so the latest numbers are always one tap away. * **All-hands progress reports:**\ One briefing, one row per team or workstream, one PDF circulated the morning of the all-hands. The AI cross-analysis surfaces the themes — leadership stops writing the recap from scratch. Rows, items, the once-a-month delivery, and the AI layers that compose the cross-source synthesis. Deeper write-ups for each use case above — agency client reporting, board prep, pitch prep, all-hands. ## Supported Integrations ### Data Sources ### Destinations Coming Soon ## Get Started Follow our step-by-step guide to set up your first automated chart delivery in under 5 minutes. ## Need Help? Read Guides Contact our support team for assistance View our code and contribute # AI Tools — Setup Source: https://docs.chartcastr.com/integrations/ai-tools Three steps to connect any MCP-compatible AI tool (Claude Code, Claude Desktop, Cursor, ChatGPT, Codex) to Chartcastr. Connect any MCP-compatible AI tool to your Chartcastr account in three steps. Pick your tool, run one command (or paste one block of JSON), restart, done. > Looking for the **why** instead of the **how**? See [AI Tools — Concepts](/integrations/ai-tools-concepts) for the context-layer and action-agent patterns. *** ## Step 1 — Get an API key In the Chartcastr dashboard, open [**Settings → API Keys**](https://chartcastr.com/admin/settings/api-keys?create=true) and create a new key. Copy it — you'll paste it in Step 2. > Treat this key like a password. Anyone with it can read your sources, connections, and pulse analysis. *** ## Step 2 — Install the MCP server in your tool Pick your tool and run the matching command. One line in your terminal: ```bash theme={null} claude mcp add --transport http chartcastr \ https://api.chartcastr.com/api/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` That's it — Claude Code persists this in your user config. Skip to Step 3. Prefer JSON? See the [Claude Code page](/integrations/claude-code) for the `.mcp.json` form. Open the config file for your platform: * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Add (or merge) this block, replacing `YOUR_API_KEY`: ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` Quit and reopen Claude. Full details on the [Claude Desktop page](/integrations/claude). Create or edit `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global): ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` Open **Cursor Settings → MCP** and toggle `chartcastr` on. Switch to **Agent** mode to use it. Full details on the [Cursor page](/integrations/cursor). Open ChatGPT Settings → **MCP Servers** → **Add server**: * **Name:** `chartcastr` * **Command:** `npx` * **Args:** `-y mcp-remote https://api.chartcastr.com/api/mcp --header X-API-Key:YOUR_API_KEY` Restart ChatGPT. For GPT Actions (REST, no MCP) and full details, see the [ChatGPT page](/integrations/chatgpt). Edit `~/.codex/config.yaml`: ```yaml theme={null} mcpServers: chartcastr: command: npx args: - "-y" - "mcp-remote" - "https://api.chartcastr.com/api/mcp" - "--header" - "X-API-Key:YOUR_API_KEY" ``` Run `codex`. Full details on the [Codex page](/integrations/codex). *** ## Step 3 — Verify it works Ask your tool one of these: * *"List my Chartcastr sources."* * *"What did the latest pulse say about my HubSpot connection?"* * *"Are any of my connections inactive?"* If you see real data come back, you're done. If not, jump to [Troubleshooting](#troubleshooting). In Claude Code or Claude Desktop, you can also run `/mcp` to see the active server list — `chartcastr` should appear. *** ## Available tools These are the tools your AI agent can call once connected: | Tool | What it returns | | ------------------- | ------------------------------------------------------------ | | `list_sources` | Every connected data source with status and connection count | | `list_destinations` | Every configured destination (Slack workspace, email, etc.) | | `list_connections` | Every active chart delivery — source, destination, cadence | | `get_latest_pulse` | Full AI narrative analysis from the most recent delivery | | `verify_connection` | Live confirmation a specific connection is active | | `open_chartcastr` | Deep link to open the dashboard at a specific page | *** ## Local development Running Chartcastr locally with `bun up`? Swap the URL to `http://localhost:8109/api/mcp` and use a key generated against your local server. ```bash theme={null} claude mcp add --transport http chartcastr-local \ http://localhost:8109/api/mcp \ --header "X-API-Key: YOUR_LOCAL_KEY" ``` *** ## Troubleshooting Your key is wrong, expired, or revoked. Regenerate at [Settings → API Keys](https://chartcastr.com/admin/settings/api-keys?create=true) and re-run the install command. Most MCP clients only load servers at startup. **Quit fully and relaunch** — a window reload isn't enough. In Claude Code, run `/mcp` to force a server-list refresh. First run downloads the `mcp-remote` package — give it \~30 seconds. If it persists, run `npx -y mcp-remote@latest` once manually to prime the cache. A specific tool may be feature-flagged off during rollout. Check [status.chartcastr.com](https://status.chartcastr.com) or contact support. # AI Tools — Concepts Source: https://docs.chartcastr.com/integrations/ai-tools-concepts Why connect AI tools to Chartcastr — the context-layer pattern, the action-agent pattern, and what becomes possible. > Looking for setup steps? See [AI Tools — Setup](/integrations/ai-tools). Chartcastr exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets any MCP-compatible AI tool — Claude Code, Cursor, ChatGPT, Codex — read your account data directly. Sources, destinations, connections, and the latest pulse analysis are all available as structured tool calls. This unlocks two distinct patterns. *** ## Pattern 1 — Context layer Your AI assistant knows more when it knows what's happening in your business. Without MCP, you describe your data situation manually. *"Revenue is down 12% this week, conversion has slipped, and we're seeing lower engagement on the enterprise tier."* You become the bridge — copying from dashboards, summarising in plain text, hoping you captured the nuance. With Chartcastr connected via MCP, your agent can fetch that analysis itself. It can pull the latest pulse — which includes not just the raw numbers but Chartcastr's contextual analysis of what changed, why it matters in the context of prior trends, and what's anomalous — and use that as the starting point for whatever you're asking it to do. This matters for coding tasks, copywriting, strategic planning, customer emails, and anything else where business context shapes the output. *** ## Pattern 2 — Action agents This is where it gets more interesting. Chartcastr runs on a schedule. Every morning (or every hour, or every week — you configure it), it ingests data from your sources, runs AI analysis against your historical context, and produces a pulse: a structured, narrative interpretation of your business right now. Previously, that pulse went to Slack or email. A human read it, decided what to do, and acted. Now you can put an agent in that loop. An action agent connects to Chartcastr via MCP, fetches the latest pulse for one or more connections, interprets the analysis, and decides what to do next: * If CAC is trending up and conversion is dropping, trigger a deep-dive analysis script * If revenue is significantly above target, generate and schedule a team celebration post * If a key metric crosses a threshold, open a GitHub issue or create a Linear ticket * If the pulse flags an anomaly, send an escalation to a specific Slack channel with additional context Chartcastr has already done the hard work: ingesting the data, normalising it, running it against prior periods, applying your business context, and producing a human-readable interpretation. Your agent doesn't need to recreate that pipeline. It just needs to read the output and decide what to do. ``` Your data sources ↓ Chartcastr (scheduled analysis, context, AI interpretation) ↓ MCP → Your AI agent ↓ Actions (Slack, GitHub, Linear, email, scripts, webhooks…) ``` *** ## What's exposed via MCP | Tool | What it returns | | ------------------- | ------------------------------------------------------------ | | `list_sources` | Every data source with status and connection count | | `list_destinations` | Every configured destination (Slack workspace, email, etc.) | | `list_connections` | Every active chart delivery — source, destination, cadence | | `get_latest_pulse` | The full AI narrative analysis from the most recent delivery | | `verify_connection` | Live confirmation that a specific connection is active | | `open_chartcastr` | Deep link to open any part of the dashboard | `get_latest_pulse` is the richest — it returns Chartcastr's full narrative analysis, not just raw numbers. This is what makes the action agent pattern work: the agent gets interpreted context, not a spreadsheet. *** ## The bigger picture Most AI tools are powerful but context-blind. They know how to reason, but they don't know what's happening in your business right now. Chartcastr is the layer that provides that context — continuously, on schedule, with full access to your data stack. The MCP integration is the bridge between Chartcastr's analysis and the agents that can act on it. Used as a simple context layer, it makes every AI conversation more grounded. Used to power action agents, it closes the loop from data → insight → action entirely. Ready to set it up? [Three-step install →](/integrations/ai-tools) # ChatGPT Source: https://docs.chartcastr.com/integrations/chatgpt Connect ChatGPT to Chartcastr and query your data from inside your conversations using the Model Context Protocol or GPT Actions. ## Overview Chartcastr supports two ways to connect with ChatGPT: 1. **MCP (ChatGPT desktop)** — The ChatGPT desktop app supports MCP servers, letting you query Chartcastr data directly from any conversation. 2. **GPT Actions** — Build a custom GPT that calls Chartcastr's REST API. Best for sharing a configured assistant with your team. *** ## Option 1: MCP via ChatGPT Desktop ### Prerequisites * ChatGPT desktop app (macOS or Windows) with MCP support enabled * A Chartcastr account on any paid plan * An API key from **Settings → API Keys** ### 1. Generate an API key In Chartcastr, go to **Settings → API Keys** and create a new key. ### 2. Add Chartcastr as an MCP server Open ChatGPT Settings and navigate to the **MCP Servers** section. Add a new server with: * **Name:** Chartcastr * **Command:** `npx` * **Args:** `-y mcp-remote https://api.chartcastr.com/api/mcp --header X-API-Key:YOUR_API_KEY` Or, if ChatGPT uses a JSON config file (check the [official ChatGPT MCP docs](https://openai.com/index/model-context-protocol-support) for the latest format): ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` ### 3. Restart ChatGPT Quit and reopen the app. Chartcastr tools should appear when you start a conversation. *** ## Option 2: GPT Actions GPT Actions let your custom GPT call Chartcastr's REST API directly. ### 1. Create a Custom GPT Go to [chatgpt.com/gpts/editor](https://chatgpt.com/gpts/editor) and click **Create a GPT**. ### 2. Add an Action Under the **Actions** tab, click **Add action** and paste Chartcastr's OpenAPI spec URL: ``` https://api.chartcastr.com/api/gpt/openapi.json ``` ### 3. Set authentication Select **API Key** as the auth type and paste your Chartcastr API key. The header name is `X-API-Key`. *** ## Available MCP Tools | Tool | Description | | ------------------- | -------------------------------------------------- | | `list_sources` | List all data sources connected to your account | | `list_destinations` | List all configured destinations | | `list_connections` | List all active chart delivery connections | | `get_latest_pulse` | Fetch the most recent AI analysis for a connection | | `verify_connection` | Confirm a connection is active | ## Further Reading * [ChatGPT MCP announcement](https://openai.com/index/model-context-protocol-support) — official OpenAI MCP guide * [Chartcastr API Keys](https://chartcastr.com/admin/settings/api-keys?create=true) — manage your keys # Claude (Desktop) Source: https://docs.chartcastr.com/integrations/claude Connect Claude's desktop app to Chartcastr via MCP and query your data sources, connections, and pulse analysis directly from your conversations. ## Overview The [Claude desktop app](https://claude.ai/download) supports MCP servers natively. Once configured, you can ask Claude about your Chartcastr account without switching to a browser. ## Prerequisites * Claude desktop app installed (macOS or Windows) * A Chartcastr account on any paid plan * An API key from **Settings → API Keys** in your Chartcastr dashboard ## Setup ### 1. Generate an API key In Chartcastr, go to **Settings → API Keys** and create a new key. ### 2. Edit the Claude config file Open the config file for your platform in a text editor: ``` ~/Library/Application Support/Claude/claude_desktop_config.json ``` ``` %APPDATA%\Claude\claude_desktop_config.json ``` If the file doesn't exist yet, create it. ### 3. Add the Chartcastr MCP server Paste the following, replacing `YOUR_API_KEY`: ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` ### 4. Restart Claude Quit and reopen the Claude desktop app. A small hammer icon will appear in the text input area when MCP tools are available. ## Available Tools | Tool | Description | | ------------------- | ----------------------------------------------------- | | `list_sources` | List all data sources connected to your account | | `list_destinations` | List all configured destinations (Slack, email, etc.) | | `list_connections` | List all active chart delivery connections | | `get_latest_pulse` | Fetch the most recent AI analysis for a connection | | `verify_connection` | Confirm a connection is active | | `open_chartcastr` | Generate a deep link to open Chartcastr | ## Example Prompts * *"What data sources do I have in Chartcastr?"* * *"Show me all my active connections."* * *"What did the latest pulse say about my HubSpot connection?"* ## Further Reading * [Claude MCP setup guide](https://modelcontextprotocol.io/quickstart/user) — official MCP docs for Claude desktop * [Chartcastr API Keys](https://chartcastr.com/admin/settings/api-keys?create=true) — manage your keys # Claude Code Source: https://docs.chartcastr.com/integrations/claude-code Connect Claude Code to Chartcastr via the Model Context Protocol and query your data, connections, and pulses directly from your AI assistant. [Claude Code](https://claude.ai/code) supports remote MCP servers natively. The fastest path is one terminal command — no JSON editing required. ## Prerequisites * A Chartcastr account on any paid plan * Claude Code installed (`npm install -g @anthropic-ai/claude-code`) * An API key from [**Settings → API Keys**](https://chartcastr.com/admin/settings/api-keys?create=true) *** ## Setup (recommended: one-liner) ```bash theme={null} claude mcp add --transport http chartcastr \ https://api.chartcastr.com/api/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with the key from your dashboard. Claude Code persists the server in your user config and loads it on next startup. To restrict the install to one project, add `--scope project`. Verify with `/mcp` — `chartcastr` should appear in the list. *** ## Setup (alternative: `.mcp.json`) Prefer to commit a project-scoped config? Create `.mcp.json` at your project root and **add it to `.gitignore`** to keep your key private: ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` Restart Claude Code or run `/mcp` to load. *** ## Available tools | Tool | Description | | ------------------- | ------------------------------------------------------- | | `list_sources` | List all data sources connected to your account | | `list_destinations` | List all configured destinations (Slack, email, etc.) | | `list_connections` | List all active chart delivery connections | | `get_latest_pulse` | Fetch the most recent pulse analysis for a connection | | `verify_connection` | Confirm a connection is active and delivering | | `open_chartcastr` | Generate a deep link to open Chartcastr in your browser | ## Example prompts * *"What data sources do I have in Chartcastr?"* * *"Show me all my active connections and their schedules."* * *"What did the latest pulse say about my HubSpot connection?"* * *"Is my Google Sheets → Slack connection still running?"* *** ## Local development Running Chartcastr locally with `bun up`? Point at your local server: ```bash theme={null} claude mcp add --transport http chartcastr-local \ http://localhost:8109/api/mcp \ --header "X-API-Key: YOUR_LOCAL_KEY" ``` *** ## Troubleshooting Your key is wrong, expired, or revoked. Regenerate at [Settings → API Keys](https://chartcastr.com/admin/settings/api-keys?create=true) and re-run `claude mcp add` (it overwrites the existing entry). Some tools may be disabled during rollout. Run `/mcp` to see what's exposed by the server, and contact support if you need access to a specific capability. Run `claude mcp list` to confirm it's registered. If it's there but Claude Code doesn't show it, fully quit and relaunch. If it's missing, the install command failed — re-run it and check the terminal output. # Codex (OpenAI) Source: https://docs.chartcastr.com/integrations/codex Connect OpenAI Codex CLI to Chartcastr via MCP and access your data sources and connections from your terminal. ## Overview [OpenAI Codex](https://github.com/openai/codex) is an open-source AI coding agent that runs in your terminal. It supports MCP servers, letting you give Codex read access to your Chartcastr account data. ## Prerequisites * Codex CLI installed (`npm install -g @openai/codex` or `pip install openai-codex`) * A Chartcastr account on any paid plan * An API key from **Settings → API Keys** Codex MCP support and config format may change as the project is actively developed. Always check the [official Codex docs](https://github.com/openai/codex) for the latest instructions. ## Setup ### 1. Generate an API key In Chartcastr, go to **Settings → API Keys** and create a new key. ### 2. Add Chartcastr to your Codex config Create or edit `~/.codex/config.yaml`: ```yaml theme={null} mcpServers: chartcastr: command: npx args: - "-y" - "mcp-remote" - "https://api.chartcastr.com/api/mcp" - "--header" - "X-API-Key:YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with the key you generated in step 1. If Codex uses a JSON config instead, use this format: ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` ### 3. Run Codex Start Codex in your terminal. It will automatically connect to any configured MCP servers at startup: ```bash theme={null} codex ``` ## Available Tools | Tool | Description | | ------------------- | ----------------------------------------------------- | | `list_sources` | List all data sources connected to your account | | `list_destinations` | List all configured destinations (Slack, email, etc.) | | `list_connections` | List all active chart delivery connections | | `get_latest_pulse` | Fetch the most recent AI analysis for a connection | | `verify_connection` | Confirm a connection is active | | `open_chartcastr` | Generate a deep link to open Chartcastr | ## Example Prompts * *"What Chartcastr sources do I have?"* * *"List my active connections and their schedules."* * *"Get the latest pulse from my Google Sheets connection."* ## Further Reading * [OpenAI Codex on GitHub](https://github.com/openai/codex) — source, docs, and config reference * [Chartcastr API Keys](https://chartcastr.com/admin/settings/api-keys?create=true) — manage your keys # Cursor Source: https://docs.chartcastr.com/integrations/cursor Connect Cursor to Chartcastr via MCP and query your data sources, connections, and pulse analysis from inside your IDE. ## Overview [Cursor](https://www.cursor.com) supports MCP servers from version 0.40 onwards. You can add Chartcastr as an MCP server so Cursor's AI can read your account data when you ask it to. ## Prerequisites * Cursor version 0.40 or later * A Chartcastr account on any paid plan * An API key from **Settings → API Keys** in your Chartcastr dashboard ## Setup ### 1. Generate an API key In Chartcastr, go to **Settings → API Keys** and create a new key. ### 2. Add Chartcastr as an MCP server You can configure MCP servers globally or per-project. Create or edit `~/.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` Create or edit `.cursor/mcp.json` in your project root: ```json theme={null} { "mcpServers": { "chartcastr": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.chartcastr.com/api/mcp", "--header", "X-API-Key:YOUR_API_KEY" ] } } } ``` Add `.cursor/mcp.json` to `.gitignore` if your key is in it. Replace `YOUR_API_KEY` with the key from step 1. ### 3. Enable the server in Cursor Settings 1. Open **Cursor Settings** → **MCP** 2. You should see `chartcastr` listed. Toggle it on. 3. Click **Refresh** if it doesn't appear immediately. ### 4. Use it in Agent mode Switch Cursor to **Agent** mode (not Ask or Edit). You can now reference Chartcastr tools in your prompts. ## Available Tools | Tool | Description | | ------------------- | ----------------------------------------------------- | | `list_sources` | List all data sources connected to your account | | `list_destinations` | List all configured destinations (Slack, email, etc.) | | `list_connections` | List all active chart delivery connections | | `get_latest_pulse` | Fetch the most recent AI analysis for a connection | | `verify_connection` | Confirm a connection is active | | `open_chartcastr` | Generate a deep link to open Chartcastr | ## Example Prompts (in Agent mode) * *"List my Chartcastr sources"* * *"Which of my connections are currently active?"* * *"Get the latest pulse for my Xero connection"* ## Further Reading * [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) — official setup guide * [Chartcastr API Keys](https://chartcastr.com/admin/settings/api-keys?create=true) — manage your keys # Destinations overview Source: https://docs.chartcastr.com/integrations/destinations Deliver Chartcastr charts and AI summaries to Slack, Microsoft Teams, Google Chat, email, or custom webhooks on an automated schedule. Chartcastr supports multiple destinations where you can automatically deliver your charts, dashboards, and data visualizations. Connect your preferred communication platforms to start sharing insights with your team. Send charts to Slack channels and direct messages Deliver reports via email to individuals or groups Deliver charts to Google Chat spaces and DMs Share visualizations in Teams channels and chats Send pulses to Ando channels and DMs (replies coming soon) ## Next Steps Learn how to set up the Slack integration and start sending pulses to your channels. # Ando destination Source: https://docs.chartcastr.com/integrations/destinations/ando Connect Chartcastr to Ando to deliver automated charts and AI summaries to your Ando conversations on a schedule. ## Overview Ando integration lets you automatically deliver charts, visualizations, and AI-powered analysis to your Ando channels and DMs. Connect once with an API key and pick the conversation that receives each pulse. **Replies and follow-up questions aren't supported yet.** Chartcastr posts the pulse and a threaded chart update, but replying in the Ando thread won't trigger an AI follow-up. We're working on it. ## Features * **Channel & DM delivery**: Send pulses to any Ando conversation your API key has access to. * **Threaded chart updates**: The chart, AI summary, and long-form analysis are grouped into a single thread per pulse. * **AI analysis included**: Every pulse includes a short summary and highlights with the chart image; the long-form analysis posts as a threaded reply. * **API key auth**: No OAuth handshake — paste a key and you're connected. * **Scheduled reports**: Daily, weekly, or custom schedules. ## Setup Open Ando and go to **Settings → API keys**. Create or copy a key (starts with `ando_sk_`). In Chartcastr, go to **Settings → Destinations** and click **Connect** next to Ando. Paste the API key. Once connected, your Ando conversations appear in the destination picker when creating or editing a connection. Select the channel or DM where charts should be delivered. Pair a data source (e.g., Google Sheets, HubSpot, Shopify) with your Ando destination and choose a schedule. ## Supported Sources Ando works with all Chartcastr data sources. ## Next Steps Set up your first chart delivery in minutes. Compare with the Slack destination, which supports reply-based AI follow-ups today. # Custom email destination (early access) Source: https://docs.chartcastr.com/integrations/destinations/custom-email Send Chartcastr reports to any email address or distribution list outside your organization. Customize subject lines and recipient groups. **State**: Coming Soon — Custom email integration is currently in development. ## Overview Custom Email allows you to send pulse reports and chart notifications to any email address, not just your logged-in account email. This is perfect for: * Distribution lists (e.g., [team@company.com](mailto:team@company.com)) * Executive stakeholders * External partners or clients * Team inboxes This is **different** from the standard [Email](/integrations/destinations/email) destination, which sends to the primary email address associated with your logged-in account. ## Planned Features * **Multiple Recipients**: Add multiple email addresses to receive the same pulse * **Distribution Lists**: Send to group email addresses * **Custom Formatting**: Tailor email content for different audiences * **Scheduling**: Set different delivery times for different recipients ## How It Will Work 1. **Add Custom Email Destination**: Navigate to [Settings → Destinations](https://chartcastr.com/admin/settings) and add a custom email address. 2. **Configure Recipients**: Specify one or more email addresses to receive notifications. 3. **Assign to Connections**: Link the custom email destination to your connections. 4. **Automatic Delivery**: Pulses will be delivered to all configured recipients. ## Early Access If you need to send pulses to custom email addresses or distribution lists, please contact us about early access. Get notified when custom email destinations are ready. # Email destination Source: https://docs.chartcastr.com/integrations/destinations/email Deliver scheduled Chartcastr charts and AI-powered summaries via email to organization members or distribution lists on a recurring schedule. ## Current Support Email integration is currently available for your logged-in account. ### How it Works This is the default email destination. When you set up an email notification, it will be sent to the primary email address associated with your login account. Support for sending to custom email addresses and distribution lists is available through [Custom Email](/integrations/destinations/custom-email). # Google Chat destination Source: https://docs.chartcastr.com/integrations/destinations/google-chat Connect Chartcastr to Google Chat to deliver automated charts and AI insights to spaces or direct messages. Set up webhooks and schedules. ## Overview Google Chat integration lets you automatically deliver charts, visualizations, and AI-powered analysis directly to Google Chat spaces and DMs. It uses your existing Google Workspace account — no extra bot tokens or service accounts required.