CLIENT API / V1 SALESFORCE

Read a stored Salesforce daily or monthly report

GET/salesforce/reports/{dataset}salesforce:read

Published local report rows. At most 366 dates or 13 calendar months. Amounts are decimal strings, separated by currency (no FX). Ratios include numerator and denominator. Observed pipeline/campaign stocks use the last actual observation in each period and are never summed over dates. A signed report_id pins publication generations, source cut and visibility epoch for 24 hours; pass it with cursor for later pages.

RequestGET https://satelliteai.io/api/v1/salesforce/reports/{dataset}
Permissionsalesforce:read
ResponseA single object: data is object.
Operation IDgetSalesforceReport

More context and worked examples are in the developer guide.

Example request

cURL · Bash
curl --fail-with-body --get \
  'https://satelliteai.io/api/v1/salesforce/reports/opportunity_creation' \
  --data-urlencode 'start_date=2026-10-01' \
  --data-urlencode 'end_date=2026-10-07' \
  -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

NameInTypeDescription
datasetrequiredpathstring
one of: lead_acquisition, lead_conversion_events, lead_cohorts, opportunity_creation, opportunity_closures, campaign_activity, primary_campaign_pipeline, opportunity_stage_history, pipeline_observed, campaign_observed · example opportunity_creation
grainquerystring
one of: day, month · default day
start_daterequiredquerystring (date)
end_daterequiredquerystring (date)
dimensionsquerystringComma-separated subset of the dataset dimensions.
max length 512
metricsquerystringComma-separated subset of the dataset metrics.
max length 512
report_idquerystring
max length 4096
limitqueryinteger
default 100 · min 1 · max 500
cursorquerystring
max length 4096
filter.currencyquerystringComma-separated values; the dataset must support this dimension.
max length 2048
filter.owner_idquerystringComma-separated values; the dataset must support this dimension.
max length 2048
filter.stagequerystringComma-separated values; the dataset must support this dimension.
max length 2048
filter.sourcequerystringComma-separated values; the dataset must support this dimension.
max length 2048
filter.campaign_idquerystringComma-separated values; the dataset must support this dimension.
max length 2048
filter.record_type_idquerystringComma-separated values; the dataset must support this dimension.
max length 2048
filter.kindquerystringComma-separated values; the dataset must support this dimension.
max length 2048
filter.statusquerystringComma-separated values; the dataset must support this dimension.
max length 2048

Unknown or repeated query parameters return 400.

Data dictionary

Report rows; metadata.status is complete, partial, pending or unavailable. Stored report with positional rows. Monetary dimensions remain currency-separated; observed stocks must not be summed over dates.

[] 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
FieldTypeDescription
data.columnsarray of object
data.columns[].namestring
data.columns[].typestring
one of: date, string, integer, decimal_string, ratio
data.rowsarray of array of string | integer | object
max items 500
data.rows[][].valuestringnullable
data.rows[][].numeratorstring
data.rows[][].denominatorstring

Response metadata

Fields in meta
FieldTypeDescription
meta.sourcestring
one of: stored
meta.access_scopestring
one of: company
meta.providerstring
one of: salesforce
meta.connection_statusstring
meta.statusstring
meta.report_idstringnullable
meta.next_cursorstringnullableOpaque cursor for the next page; send as cursor. Null on the last page.
meta.timezonestring
meta.pending_monthsarray of string
meta.request_idstringSupport request ID, also returned in X-Request-ID.
meta.api_versionstringAPI version that produced the response.
one of: v1
meta.coverage_notestringRecords/fields are limited to the connected Salesforce source user.
meta.datasetstring
meta.grainstring
one of: day, month
meta.kindstring
one of: flow, observed
meta.unavailable_monthsarray of string
meta.stale_monthsarray of string
meta.partial_periodsarray of string
meta.unavailable_metricsmap of array of stringUnavailable metric names keyed by calendar month.
meta.completed_dates_throughmap of string (date)Last fully completed local date per published month.
meta.source_cutsmap of integerStored source cut per month, pinned by report_id.
meta.published_atmap of string (date-time)Publication timestamps per month.
meta.currency_semanticsstring
meta.semanticsstring
meta.freshness_statusstring
meta.labelsmap of stringnullableCurrent labels keyed by dimension:ID; only with salesforce:records:read.
meta.observationsmap of objectActual observation per returned period; never reconstructed.
meta.observations.{key}.observed_atstring (date-time)nullable
meta.observations.{key}.observation_cutinteger
meta.observations.{key}.raw_detail_expires_atstring (date-time)nullable
meta.observations.{key}.source_spanobject
meta.observation_ages_hoursmap of number
meta.unobserved_periodsstring
meta.object_typestring
meta.source_cutinteger
meta.raw_detail_expires_atstring (date-time)nullable
meta.approved_fieldsarray of string
meta.target_rangeobject
meta.target_range.start_datestring (date)
meta.target_range.end_datestring (date)
meta.target_range.monthsinteger
meta.target_range.includes_mtdboolean

Error responses

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

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