Inspect Salesforce connection

GET/salesforce/connectionsalesforce:read

OVERVIEW

Company-wide stored CRM access delegated by a company-wide administrator. Site and business-unit grants never confer Salesforce access. No provider call, collection scheduling or credit deduction. Coverage is limited to records visible to the connected Salesforce source user.

Request	`GET https://satelliteai.io/api/v1/salesforce/connection`
Permission	`salesforce:read`
Response	A single object: `data` is `SalesforceConnection`.
Operation ID	`getSalesforceConnection`

More context and worked examples are in the developer guide.

REQUEST

Example request

cURL · Bash

curl --fail-with-body \
  'https://satelliteai.io/api/v1/salesforce/connection' \
  -H "Authorization: Bearer $SATELLITE_API_KEY"

Replace the example IDs with values returned by the discovery endpoints. Example values are placeholders, not real records.

Parameters

No parameters. Send only the Authorization header.

Unknown or repeated query parameters return 400.

RESPONSE

Data dictionary

Stored connection state. source_user_name requires salesforce:records:read.

[] marks an array element. nullable means the value can be null; treat it as unknown, not zero. always present means the key is always included in the object.

Fields in data
Field	Type	Description
`data.connected`	boolean
`data.status`	stringnullable	one of: active, needs_reauth, disconnected, not_connected, None
`data.environment`	stringnullable	one of: production, sandbox, None
`data.source_org_id`	stringnullable
`data.source_user_name`	stringnullable
`data.reporting_timezone`	stringnullable
`data.org_currency`	stringnullable
`data.connected_at`	string (date-time)nullable
`data.last_health_at`	string (date-time)nullable
`data.last_refreshed_at`	string (date-time)nullable
`data.access_scope`	string	one of: company
`data.stored_only`	boolean
`data.datasets`	array of string

Response metadata

Fields in meta
Field	Type	Description
`meta.source`	string	one of: stored
`meta.access_scope`	string	one of: company
`meta.provider`	string	one of: salesforce
`meta.connection_status`	string
`meta.status`	string
`meta.report_id`	stringnullable
`meta.next_cursor`	stringnullable	Opaque cursor for the next page; send as cursor. Null on the last page.
`meta.timezone`	string
`meta.pending_months`	array of string
`meta.request_id`	string	Support request ID, also returned in X-Request-ID.
`meta.api_version`	string	API version that produced the response. one of: v1
`meta.coverage_note`	string	Records/fields are limited to the connected Salesforce source user.
`meta.dataset`	string
`meta.grain`	string	one of: day, month
`meta.kind`	string	one of: flow, observed
`meta.unavailable_months`	array of string
`meta.stale_months`	array of string
`meta.partial_periods`	array of string
`meta.unavailable_metrics`	map of array of string	Unavailable metric names keyed by calendar month.
`meta.completed_dates_through`	map of string (date)	Last fully completed local date per published month.
`meta.source_cuts`	map of integer	Stored source cut per month, pinned by report_id.
`meta.published_at`	map of string (date-time)	Publication timestamps per month.
`meta.currency_semantics`	string
`meta.semantics`	string
`meta.freshness_status`	string
`meta.labels`	map of stringnullable	Current labels keyed by dimension:ID; only with salesforce:records:read.
`meta.observations`	map of object	Actual observation per returned period; never reconstructed.
`meta.observations.{key}.observed_at`	string (date-time)nullable
`meta.observations.{key}.observation_cut`	integer
`meta.observations.{key}.raw_detail_expires_at`	string (date-time)nullable
`meta.observations.{key}.source_span`	object
`meta.observation_ages_hours`	map of number
`meta.unobserved_periods`	string
`meta.object_type`	string
`meta.source_cut`	integer
`meta.raw_detail_expires_at`	string (date-time)nullable
`meta.approved_fields`	array of string
`meta.target_range`	object
`meta.target_range.start_date`	string (date)
`meta.target_range.end_date`	string (date)
`meta.target_range.months`	integer
`meta.target_range.includes_mtd`	boolean

ERRORS

Error responses

Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.

HTTP	When
`400`	Unknown/repeated or invalid query parameters; live/refresh and scope overrides are not accepted.
`401`	Missing, invalid, revoked or expired API key.
`403`	Required Salesforce permission is missing, or company-wide CRM access is not permitted.
`404`	Missing or inaccessible resource.
`409`	report_expired, invalid_cursor, cursor_expired or records_expired: restart without expired tokens. report_month_required: select a month belonging to the pinned flow report.
`413`	Public response size limit exceeded; request fewer rows.
`429`	Request allowance exceeded.
`503`	Existing integration storage or API dependencies are unavailable.