Rippling: Trigger a report run
Rippling restApi.triggerReportRuns: arguments, response, policy and SDK examples.
← Rest API operations · Get started
Operation rippling.rest_api.trigger_report_runs
Provider route: POST /report-runs/. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/rippling with npm, or alter-sdk-rippling with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { RipplingIntegration } from "@alter-ai/rippling";
async function execute(input: Parameters<RipplingIntegration["restApi"]["triggerReportRuns"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new RipplingIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.restApi.triggerReportRuns(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_rippling import RipplingIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = RipplingIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.rest_api.trigger_report_runs(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | Model | Optional | Expand Trigger a report run — request body — body |
Referenced models: Trigger a report run — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
id | string | Required within parent | The ID of this run |
report_id | string | Required within parent | The ID of the report associated with this run |
result | object | Optional | Report data, available once the run is complete |
result.expires_at | string | Required within parent | The expiry time of the execution |
result.file_url | string | Required within parent | The presigned file url |
result.output_type | string | Required within parent | The type of the output file Known values: JSON, CSV |
status | string | Required within parent | Report run status Known values: IN_PROGRESS, SUCCESS, FAILURE |
Schemas
Section titled “Schemas”Trigger a report run — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
filters | JSON | Optional | |
filters (anyOf 1) | array | Alternative | Optional list of filters to apply when running the report Default: null |
filters (anyOf 1)[] | Model | Each item | Expand Trigger a report run — request body — body filters array item |
filters (anyOf 2) | null | Alternative | |
format_currency_fields | JSON | Optional | |
format_currency_fields (anyOf 1) | JSON | Alternative | Formatting options for currency fields Default: null |
format_currency_fields (anyOf 1) (anyOf 1) | object | Alternative | |
format_currency_fields (anyOf 1) (anyOf 1).columns | string | Required within parent | Currency column format for currency fields One of: TYPE_AND_AMOUNT, VALUE_ONLY |
format_currency_fields (anyOf 1) (anyOf 1).currency_type | JSON | Optional | |
format_currency_fields (anyOf 1) (anyOf 1).currency_type (anyOf 1) | string | Alternative | Currency type (e.g., 'USD') |
format_currency_fields (anyOf 1) (anyOf 1).currency_type (anyOf 2) | null | Alternative | |
format_currency_fields (anyOf 1) (anyOf 2) | null | Alternative | |
format_currency_fields (anyOf 2) | null | Alternative | |
format_date_fields | JSON | Optional | |
format_date_fields (anyOf 1) | JSON | Alternative | Formatting options for date fields Default: null |
format_date_fields (anyOf 1) (anyOf 1) | object | Alternative | |
format_date_fields (anyOf 1) (anyOf 1).date_format | string | Required within parent | Date format for date fields in the report output One of: ISO_8601, APPLY_VISUALIZATION_SETTINGS |
format_date_fields (anyOf 1) (anyOf 1).datetime_timezone | JSON | Optional | |
format_date_fields (anyOf 1) (anyOf 1).datetime_timezone (anyOf 1) | string | Alternative | Timezone for datetime fields (e.g., 'America/Los_Angeles') |
format_date_fields (anyOf 1) (anyOf 1).datetime_timezone (anyOf 2) | null | Alternative | |
format_date_fields (anyOf 1) (anyOf 2) | null | Alternative | |
format_date_fields (anyOf 2) | null | Alternative | |
include_object_ids | boolean | Optional | Whether to include object IDs in the report output Default: false |
include_total_rows | boolean | Optional | Whether to include total row count in the report output Default: false |
output_type | string | Optional | Output format for the report data Default: JSON One of: JSON, CSV |
report_id | string | Required within parent | The ID of the report to run |
view_as | string | Optional | Controls whose permissions are used when running the report. VIEWER (default) uses the API token owner's own permissions. OWNER uses the report owner's permissions (requires owner-level access to the report). Default: VIEWER One of: VIEWER, OWNER |
Referenced models: Trigger a report run — request body — body filters array item
Trigger a report run — request body — body filters array item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A single filter to apply when running a report. The expected shape of 'value' depends on the operator — see the FilterOperator description for details. |
field_id | string | Required within parent | The ID of the report field to filter on |
operator | string | Required within parent | Comparison operator for the filter. Single-value operators (EQ, NE, GT, GTE, LT, LTE, STARTS_WITH, ENDS_WITH, CONTAINS, NOT_CONTAINS, BEFORE, AFTER) require a scalar value. List operators (IN, NOT_IN) require a non-empty array. Range operators (BETWEEN, NOT_BETWEEN) require an object with 'from' and 'to' keys. No-value operators (IS_EMPTY, IS_NOT_EMPTY) do not require a value. Rolling-date operators (LAST_N, NEXT_N) require an object with 'unit' (DAY, WEEK, MONTH, YEAR) and 'n' (integer). Calendar-date operators (CURRENT_CALENDAR, PREVIOUS_CALENDAR) require a unit string (DAY, WEEK, MONTH, QUARTER, YEAR). One of: EQ, NE, IN, NOT_IN, STARTS_WITH, ENDS_WITH, CONTAINS, NOT_CONTAINS, GT, GTE, LT, LTE, BETWEEN, NOT_BETWEEN, IS_EMPTY, IS_NOT_EMPTY, BEFORE, AFTER, LAST_N, NEXT_N, CURRENT_CALENDAR, PREVIOUS_CALENDAR |
value | JSON | Optional | |
value (anyOf 1) | JSON | Alternative | The filter value. Shape depends on the operator: scalar for single-value operators; array for list operators; RangeValue object ({from, to}) for range operators; RollingDateValue object ({unit, n}) for rolling-date operators; unit string for calendar-date operators; omitted or null for IS_EMPTY/IS_NOT_EMPTY. |
value (anyOf 1) (oneOf 1) | string | Alternative | |
value (anyOf 1) (oneOf 2) | number | Alternative | |
value (anyOf 1) (oneOf 3) | boolean | Alternative | |
value (anyOf 1) (oneOf 4) | array | Alternative | |
value (anyOf 1) (oneOf 5) | Model | Alternative | Expand Trigger a report run — request body — body filters array item value value from, to |
value (anyOf 1) (oneOf 6) | Model | Alternative | Expand Trigger a report run — request body — body filters array item value value n, unit |
value (anyOf 2) | null | Alternative |
Referenced models: Trigger a report run — request body — body filters array item value value from, to, Trigger a report run — request body — body filters array item value value n, unit
Trigger a report run — request body — body filters array item value value from, to
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Range bounds for 'between' and 'not_between' operators |
Trigger a report run — request body — body filters array item value value n, unit
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Rolling date window for 'last_n' and 'next_n' operators |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: rippling.rest_api.trigger_report_runs. Catalog operation: trigger-report-runs. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["report-runs.read-write"]
Provider entitlements: ["Reports_API"]
Pinned headers: {"Rippling-Api-Version": "2024-08-01"}