Read a stored Salesforce daily or monthly report
/salesforce/reports/{dataset}salesforce:readPublished 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.
| Request | GET https://satelliteai.io/api/v1/salesforce/reports/{dataset} |
| Permission | salesforce:read |
| Response | A single object: data is object. |
| Operation ID | getSalesforceReport |
More context and worked examples are in the developer guide.
Example request
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
| Name | In | Type | Description |
|---|---|---|---|
datasetrequired | path | string | 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 |
grain | query | string | one of: day, month · default day |
start_daterequired | query | string (date) | |
end_daterequired | query | string (date) | |
dimensions | query | string | Comma-separated subset of the dataset dimensions. max length 512 |
metrics | query | string | Comma-separated subset of the dataset metrics. max length 512 |
report_id | query | string | max length 4096 |
limit | query | integer | default 100 · min 1 · max 500 |
cursor | query | string | max length 4096 |
filter.currency | query | string | Comma-separated values; the dataset must support this dimension. max length 2048 |
filter.owner_id | query | string | Comma-separated values; the dataset must support this dimension. max length 2048 |
filter.stage | query | string | Comma-separated values; the dataset must support this dimension. max length 2048 |
filter.source | query | string | Comma-separated values; the dataset must support this dimension. max length 2048 |
filter.campaign_id | query | string | Comma-separated values; the dataset must support this dimension. max length 2048 |
filter.record_type_id | query | string | Comma-separated values; the dataset must support this dimension. max length 2048 |
filter.kind | query | string | Comma-separated values; the dataset must support this dimension. max length 2048 |
filter.status | query | string | Comma-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.
| Field | Type | Description |
|---|---|---|
data.columns | array of object | |
data.columns[].name | string | |
data.columns[].type | string | one of: date, string, integer, decimal_string, ratio |
data.rows | array of array of string | integer | object | max items 500 |
data.rows[][].value | stringnullable | |
data.rows[][].numerator | string | |
data.rows[][].denominator | string |
Response metadata
| 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 |
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. |