Salesforce

Connect a Salesforce org to Better Analyst with OAuth, choose the objects it may query, pin saved reports, and analyze CRM data in chat, dashboards, alerts, and Data Flows.

Connect Salesforce to Better Analyst to analyze accounts, opportunities, leads, cases, campaigns, activities, and custom objects. Better Analyst runs read-only SOQL queries against the objects you select, runs the saved reports you pin, and never asks you to paste a password or security token.

Requirements

  • A Salesforce user with API Enabled and read access to the objects you want to analyze
  • An org edition with API access (Enterprise, Unlimited, Performance, Developer, or Professional with API access)
  • Permission to approve the api, refresh_token/offline_access, and id OAuth scopes

Choose which Salesforce app connects

The connector page offers two ways to connect:

  • Connect with Better Analyst's app: one click, once your Salesforce org can use Better Analyst's app (see below).
  • Use your organization's own Salesforce app: your Salesforce admin creates an app in your own org and gives Better Analyst its consumer key and secret. Use this if your org can't use Better Analyst's app yet, or if your security policy requires apps your org owns. See Use your organization's own Salesforce app.

First connection: your Salesforce admin installs the app

Since September 2025, Salesforce blocks users from authorizing apps their org has not installed. Before the first person in your org connects, a Salesforce admin should open Setup → Connected Apps OAuth Usage, find Better Analyst, and select Install. After that, anyone in the org with the requirements above can connect. Alternatively, the admin can grant the connecting user the Approve Uninstalled Connected Apps permission.

Use a read-only integration user

Salesforce has no read-only OAuth scope. The api scope grants the connecting user's full API rights, so what Better Analyst could do is limited by that user's profile and permission sets, not by the scope. Better Analyst itself only sends SOQL SELECT queries and Bulk API 2.0 query jobs, and rejects DML, FOR UPDATE, and ALL ROWS before a request leaves the app.

For defense in depth, connect with a dedicated integration user whose permission set grants Read on the objects you need and nothing else. Field-level security on that user also decides which fields Better Analyst can see.

Connect an org

  1. Go to Connectors, then Salesforce.
  2. Choose where you sign in:
    • Production for login.salesforce.com
    • Sandbox for test.salesforce.com
    • My Domain for a host such as acme.my.salesforce.com or acme--uat.sandbox.my.salesforce.com
  3. Select Continue with Salesforce and approve access.
  4. Choose the objects Better Analyst may query. Common objects (Account, Contact, Lead, Opportunity, Case, Campaign, User, Task, Event, and Opportunity History) are preselected when your org has them. Search to add custom __c objects. You can select up to 40 objects.
  5. Name the connector and save it.

Each Salesforce org can be connected once per workspace. Connectors created in a team workspace are available to the team.

Use Manage to change which objects are selected, and Refresh selected schema after fields or picklist values change in Salesforce.

Use your organization's own Salesforce app

A Salesforce admin sets this up once. After that, anyone in the workspace can connect with it.

  1. In Salesforce, open Setup → External Client App Manager and choose New External Client App. Keep the distribution state Local.
  2. Turn on Enable OAuth and set the Callback URL to exactly the URL shown on the Better Analyst connector page, for example https://app.betteranalyst.com/api/salesforce/callback.
  3. Add these OAuth scopes:
    • Manage user data via APIs (api)
    • Perform requests at any time (refresh_token, offline_access)
    • Access the identity URL service (id, profile, email, address, phone)
  4. Under security settings, turn on Require secret for Web Server Flow, Require secret for Refresh Token Flow, and Require Proof Key for Code Exchange (PKCE). Leave the other flows off.
  5. Save the app. In its Policies, choose who may use it: all users may self-authorize, or admin-approved users assigned through profiles or permission sets. We recommend refresh token rotation.
  6. Under Settings → OAuth Settings, choose Consumer Key and Secret and copy both. A new app can take a few minutes to start working.
  7. In Better Analyst, open Connectors → Salesforce, choose Use your organization's own Salesforce app, and enter your My Domain URL (from Setup → My Domain, for example https://acme.my.salesforce.com), the Consumer Key, and the Consumer Secret. Select Connect and approve access.

Better Analyst stores the consumer secret encrypted and never shows it again. In a team workspace, the app belongs to the team: its creator or a team owner or admin can update the key or secret, or remove it. An app can't be removed while a Salesforce data source uses it. Reconnecting, and teammates connecting their own Salesforce login to a shared data source, use the same app automatically.

Saved reports

Pin saved Salesforce reports when you want answers that match a report your team already trusts, with its filters, groupings, and formula columns.

  1. On the Salesforce connector page, choose Manage on a connected org.
  2. Open the Reports tab, search by report name, and select up to 50 reports.
  3. Choose Save pinned reports.

Chat can run only pinned reports. Ask for one by name, for example "Use the Pipeline by Stage report to show this quarter's closed-won deals by owner."

  • Formats: tabular, summary, and matrix reports are supported. Joined reports cannot be pinned. Query their objects directly instead.
  • Rows: Salesforce returns the first 2,000 detail rows of each report run. When a report has more, the result is marked partial and Better Analyst offers a full SOQL query instead. Summary and matrix reports arrive as one table, with a column for each grouping.
  • Filters and dates: chat can add up to 20 filters to a run and replace the report's standard date range. The saved report in Salesforce never changes.
  • Access: reports run as the connected Salesforce user, so that user's report-folder sharing and field-level security decide what a run returns.
  • Limits: Salesforce allows 500 synchronous report runs per org per hour and 20 at a time. Dashboard refreshes of pinned reports count toward this limit.
  • Changes in Salesforce: if someone edits a pinned report's columns, save the pinned reports again so chat sees the new columns. A Data Flow built on that report stops with a schema-change error; rebuild it from a new chat result.

Pipeline history

Opportunity History records each change to an opportunity's stage, amount, close date, and probability. Use it to ask how the pipeline changed over time, how long deals spend in each stage, or which close dates slipped.

Other history objects, such as Account History or Case History, record only the fields your admin set up for history tracking (up to 20 per object). Salesforce keeps that history for about 18 months in its interface and 24 months through the API, so Better Analyst can't see older changes.

Currency

If your org uses multiple currencies, Better Analyst records the corporate currency when it reads your schema. It then converts amounts with convertCurrency(), and filters amounts with currency-coded values such as USD5000. Totals from aggregate queries are in the corporate currency. Where advanced currency management is on, opportunities, opportunity products, and opportunity history use dated exchange rates. In report results, each amount column gets a matching currency column.

Data behavior

  • Better Analyst writes SOQL SELECT queries against the selected objects. Queries that reference any other object are refused.
  • Parent relationship fields such as Account.Name and semi-joins over selected objects are supported. Parent-to-child subqueries and TYPEOF are not.
  • Preview requests return at most 1,000 rows. Larger and complete results are capped at 250,000 rows.
  • Large record exports run as Bulk API 2.0 query jobs. Aggregate queries (COUNT, SUM, GROUP BY) use the REST query API.
  • Pinned reports run through the Salesforce Reports API and return at most 2,000 detail rows per run.
  • Dashboard refreshes, scheduled refreshes, alerts, and Data Flows replay the saved structured Salesforce request (a SOQL query or a pinned report run) with the dashboard's date range. They do not infer a new query from chat text. A Data Flow refuses a report run that Salesforce cut off at 2,000 rows.

API limits

Queries count against your org's daily API request allocation, and Bulk API jobs count against Bulk API limits. Better Analyst does not charge a separate Salesforce fee. Filter by date range or narrow the object list to keep usage low.

Disconnect and retention

Deleting the last Better Analyst connector that references a Salesforce authorization removes Better Analyst's stored OAuth tokens. Generated dataset artifacts follow Better Analyst's normal retention settings.

To revoke Better Analyst in Salesforce as well, open Setup → Connected Apps OAuth Usage, find the Better Analyst app, and revoke it, or remove the app from the user's Personal Information → Connected Apps list.

If Salesforce reports an expired or revoked session, choose Reconnect on the connector page. Refresh tokens can expire if your admin set a refresh token policy other than "valid until revoked".

Troubleshooting

  • Reconnect required: authorize Salesforce again; Better Analyst never exposes stored tokens.
  • Object missing from the list: confirm the connecting user can read the object and that it is queryable through the API.
  • Field missing: check field-level security for the connecting user, then use Refresh selected schema.
  • "Your Salesforce org has not approved Better Analyst yet" (OAUTH_APP_BLOCKED or OAUTH_APP_ACCESS_DENIED): ask a Salesforce admin to install the app as described in First connection, or to allow it for your profile.
  • IP restriction errors: ask your Salesforce admin to relax IP restrictions for the Better Analyst app.
  • "Salesforce rejected the app's consumer key or secret": copy both values again from your Salesforce app's Consumer Key and Secret page, and update them on the connector page.
  • "The callback URL in your Salesforce app must be exactly …" or redirect_uri_mismatch: set your Salesforce app's callback URL to the exact URL shown on the connector page, with no trailing slash, then wait a few minutes.
  • API limit exceeded: wait for the daily allocation to reset or narrow the request.
  • Report run limit reached: Salesforce allows 500 synchronous report runs per hour. Wait, or ask chat to use a SOQL query instead.
  • Report missing from the Reports tab: confirm the connecting user can see the report's folder. Joined reports show as not supported.

Next steps