The Faraday connector lets your AI agent act in each user's Faraday account. Each user connects their own Faraday access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 58 tools.
- Tools
- 58
- What they doRead · write · destructive
- 34 · 19 · 534 read19 write5 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Faraday connection
In AgentKit > Connections, create a Faraday connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'faraday'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Faraday:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'faraday_account_get',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "faraday"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Faraday:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="faraday_account_get",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Faraday credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolfaraday_account_getGet the account the API key belongs to.Read-onlyGet Current Account
Get the account the API key belongs to. Returns the account with id, name and settings. Use faraday_account_get to check the connection.
Inputs
This tool takes no inputs.
faraday_attributes_listList the Faraday Identity Graph attributes available for cohorts, persona sets and outcomes.Read-onlyList Attributes
List the Faraday Identity Graph attributes available for cohorts, persona sets and outcomes. Returns an array of attributes with name, literate, category and type. Use faraday_attributes_list to pick attribute names such as fdy/age for cohort filters.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_cohort_getGet one cohort by UUID.Read-onlyGet Cohort
Get one cohort by UUID. Returns the cohort with its configuration, status and build details. Use faraday_cohort_get to check whether it is ready.
Inputs
cohort_idstringrequired- UUID of the cohort. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_cohort_membership_getGet a cohort's membership counts over time.Read-onlyGet Cohort Membership
Get a cohort's membership counts over time. Returns membership statistics. Use faraday_cohort_membership_get to see how large a cohort is.
Inputs
cohort_idstringrequired- UUID of the cohort. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_cohorts_listList the account's cohorts (groups of people defined by stream events, traits or attributes).Read-onlyList Cohorts
List the account's cohorts (groups of people defined by stream events, traits or attributes). Returns an array of cohorts with id, name, population count and status. Use faraday_cohorts_list to find a cohort ID for outcomes, persona sets and scopes.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_connection_getGet one connection by UUID.Read-onlyGet Connection
Get one connection by UUID. Returns the connection with type and status (secrets are not returned). Use faraday_connection_get to check a connection.
Inputs
connection_idstringrequired- UUID of the connection. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_connections_listList the account's data connections (warehouses, buckets, CRMs).Read-onlyList Connections
List the account's data connections (warehouses, buckets, CRMs). Returns an array of connections with id, name, type and status. Use faraday_connections_list to get a connection_id for datasets and targets.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_dataset_getGet one dataset by UUID.Read-onlyGet Dataset
Get one dataset by UUID. Returns the dataset with its configuration, status and build details. Use faraday_dataset_get to check whether it is ready.
Inputs
dataset_idstringrequired- UUID of the dataset. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_datasets_listList the account's datasets (data sources mapped to identities, streams and traits).Read-onlyList Datasets
List the account's datasets (data sources mapped to identities, streams and traits). Returns an array of datasets with id, name, status, row counts and outputs. Use faraday_datasets_list to find a dataset. Use faraday_dataset_get for details.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_forecast_analysis_getGet a forecast's performance analysis.Read-onlyGet Forecast Analysis
Get a forecast's performance analysis. Returns analysis results. Use faraday_forecast_analysis_get to judge accuracy.
Inputs
forecast_idstringrequired- UUID of the forecast. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_forecast_getGet one forecast by UUID.Read-onlyGet Forecast
Get one forecast by UUID. Returns the forecast with its configuration, status and build details. Use faraday_forecast_get to check whether it is ready.
Inputs
forecast_idstringrequired- UUID of the forecast. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_forecasts_listList the account's forecasts (models of future value such as revenue per customer).Read-onlyList Forecasts
List the account's forecasts (models of future value such as revenue per customer). Returns an array of forecasts with id, name, streams, horizon and status. Use faraday_forecasts_list to find a forecast ID.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_outcome_analysis_getGet an outcome's model performance and feature importance.Read-onlyGet Outcome Analysis
Get an outcome's model performance and feature importance. Returns analysis with performance metrics, lift and feature importance. Use faraday_outcome_analysis_get to judge model quality.
Inputs
outcome_idstringrequired- UUID of the outcome. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_outcome_getGet one outcome by UUID.Read-onlyGet Outcome
Get one outcome by UUID. Returns the outcome with its configuration, status and build details. Use faraday_outcome_get to check whether it is ready.
Inputs
outcome_idstringrequired- UUID of the outcome. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_outcomes_listList the account's outcomes (predictive models of who will reach a goal).Read-onlyList Outcomes
List the account's outcomes (predictive models of who will reach a goal). Returns an array of outcomes with id, name, cohorts, status and performance. Use faraday_outcomes_list to find an outcome ID for scopes.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_persona_set_dimensions_getGet how each persona differs across dimensions.Read-onlyGet Persona Set Dimensions
Get how each persona differs across dimensions. Returns per-persona statistics by attribute. Use faraday_persona_set_dimensions_get to describe personas.
Inputs
persona_set_idstringrequired- UUID of the persona set. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_persona_set_getGet one persona set by UUID.Read-onlyGet Persona Set
Get one persona set by UUID. Returns the persona set with its configuration, status and build details. Use faraday_persona_set_get to check whether it is ready.
Inputs
persona_set_idstringrequired- UUID of the persona set. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_persona_sets_listList the account's persona sets (clusters of a cohort into personas).Read-onlyList Persona Sets
List the account's persona sets (clusters of a cohort into personas). Returns an array of persona sets with id, name, cohort and personas. Use faraday_persona_sets_list to find a persona set ID for scopes.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_place_getGet one place by UUID.Read-onlyGet Place
Get one place by UUID. Returns the place with its configuration, status and build details. Use faraday_place_get to check whether it is ready.
Inputs
place_idstringrequired- UUID of the place. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_places_listList the account's places (geographic areas from addresses or GeoJSON).Read-onlyList Places
List the account's places (geographic areas from addresses or GeoJSON). Returns an array of places with id, name and geometry. Use faraday_places_list to find a place for cohort location filters.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_recommender_analysis_getGet a recommender's performance analysis.Read-onlyGet Recommender Analysis
Get a recommender's performance analysis. Returns analysis results. Use faraday_recommender_analysis_get to judge it.
Inputs
recommender_idstringrequired- UUID of the recommender. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_recommender_getGet one recommender by UUID.Read-onlyGet Recommender
Get one recommender by UUID. Returns the recommender with its configuration, status and build details. Use faraday_recommender_get to check whether it is ready.
Inputs
recommender_idstringrequired- UUID of the recommender. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_recommenders_listList the account's recommenders (models predicting which stream property value a person will choose next).Read-onlyList Recommenders
List the account's recommenders (models predicting which stream property value a person will choose next). Returns an array of recommenders with id, name, stream and status. Use faraday_recommenders_list to find a recommender ID for scopes.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_scope_analysis_getGet a scope's analysis of its population and predictions.Read-onlyGet Scope Analysis
Get a scope's analysis of its population and predictions. Returns analysis results. Use faraday_scope_analysis_get to review a scope before exporting.
Inputs
scope_idstringrequired- UUID of the scope. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_scope_getGet one scope by UUID.Read-onlyGet Scope
Get one scope by UUID. Returns the scope with its configuration, status and build details. Use faraday_scope_get to check whether it is ready.
Inputs
scope_idstringrequired- UUID of the scope. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_scopes_listList the account's scopes (which predictions to compute for which population).Read-onlyList Scopes
List the account's scopes (which predictions to compute for which population). Returns an array of scopes with id, name, payload, population and status. Use faraday_scopes_list to find a scope ID for targets.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_stream_getGet one stream by UUID or name.Read-onlyGet Stream
Get one stream by UUID or name. Returns the stream with its properties and statistics. Use faraday_stream_get to see a stream's properties.
Inputs
stream_id_or_namestringrequired- UUID or name of the stream. Example: orders.
faraday_streams_listList event streams created from datasets (for example orders or signups).Read-onlyList Streams
List event streams created from datasets (for example orders or signups). Returns an array of streams with name, properties and event counts. Use faraday_streams_list to find stream names for cohorts, recommenders and forecasts.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_target_getGet one target by UUID.Read-onlyGet Target
Get one target by UUID. Returns the target with its configuration, status and build details. Use faraday_target_get to check whether it is ready.
Inputs
target_idstringrequired- UUID of the target. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_targets_listList the account's targets (exports of a scope's results to files, warehouses or the lookup API).Read-onlyList Targets
List the account's targets (exports of a scope's results to files, warehouses or the lookup API). Returns an array of targets with id, name, scope, representation and status. Use faraday_targets_list to find a target ID.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_trait_getGet one trait by UUID.Read-onlyGet Trait
Get one trait by UUID. Returns the trait with its configuration, status and build details. Use faraday_trait_get to check whether it is ready.
Inputs
trait_idstringrequired- UUID of the trait. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_traits_listList the account's traits (named person properties from datasets or Faraday).Read-onlyList Traits
List the account's traits (named person properties from datasets or Faraday). Returns an array of traits with id, name, type and source. Use faraday_traits_list to find trait names for cohort filters.
Inputs
idsstring- Comma-separated IDs to return only those records. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_uploads_listList files uploaded to the account's hosted CSV storage.Read-onlyList Uploads
List files uploaded to the account's hosted CSV storage. Returns an array of uploads with directory, filename and size. Use faraday_uploads_list to see which CSV files a hosted_csv dataset can read.
Inputs
This tool takes no inputs.
faraday_usages_getGet the account's usage against its limits (rows ingested, rows exported, resources).Read-onlyGet Usage
Get the account's usage against its limits (rows ingested, rows exported, resources). Returns usage counters. Use faraday_usages_get before large exports.
Inputs
This tool takes no inputs.
faraday_cohort_createCreate a cohort from a stream's events, optionally filtered by traits, attributes, event counts or values, and recency.WriteCreate Cohort
Create a cohort from a stream's events, optionally filtered by traits, attributes, event counts or values, and recency. Returns the cohort with id and status. Use faraday_cohort_create to define customers, leads or churners.
Inputs
namestringrequired- Human-readable name, unique in the account. Example: Customers.
attributesarray- List of attribute conditions to filter cohort membership. Only available if your account has an identity graph feature store set. Attribute conditions and trait conditions merge into one list. Required conditions (optional=false) AND together. Optional conditions (optional=true) OR together as a group. Both groups AND-ed for final membership. Example: [{"name": "fdy/age", "gte": 30}]
location_conditionsarray- List of atlas locations to use to spatially filter Cohort membership. A cohort may not set both location_conditions and place_conditions. Example: [{"location_id": "9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e"}]
max_countnumber- Max count for this cohort's config. Example: 10.
max_valuenumber- Max value for this cohort's config. Example: 5000.
min_countnumber- Min count for this cohort's config. Example: 1.
min_valuenumber- Min value for this cohort's config. Example: 100.
recencyobject- (Parameters used to POST a new value of the Recency type.) Basing cohort on recency of event. Example: {"min_days": 0, "max_days": 365}
stream_conditionsarray- List of stream properties to filter cohort membership on. The stream properties must be for the same stream set as the cohort stream_name. Nulls are excluded unless explicitly requested with _null: true. Example: [{"property": "total", "gte": 50}]
stream_namestring- The name field of the stream from which to build this cohort. Example: orders.
traitsarray- List of traits to filter cohort membership. Example: [{"name": "plan_tier", "eq": "gold"}]
faraday_cohort_updateUpdate a cohort's definition; only the fields you send change.WriteUpdate Cohort
Update a cohort's definition; only the fields you send change. Returns the updated cohort. Use faraday_cohort_update to change its filters.
Inputs
cohort_idstringrequired- UUID of the cohort. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
attributesarray- List of attribute conditions to filter cohort membership. Only available if your account has an identity graph feature store set. Attribute conditions and trait conditions merge into one list. Required conditions (optional=false) AND together. Optional conditions (optional=true) OR together as a group. Both groups AND-ed for final membership. Example: [{"name": "fdy/age", "gte": 30}]
location_conditionsarray- List of atlas locations to use to spatially filter Cohort membership. A cohort may not set both location_conditions and place_conditions. Example: [{"location_id": "9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e"}]
max_countnumber- Max count for this cohort's config. Example: 10.
max_valuenumber- Max value for this cohort's config. Example: 5000.
min_countnumber- Min count for this cohort's config. Example: 1.
min_valuenumber- Min value for this cohort's config. Example: 100.
namestring- Human-readable name, unique in the account. Example: Customers.
recencyobject- Recency. Example: {"min_days": 0, "max_days": 365}
stream_conditionsarray- List of stream properties to filter cohort membership on. The stream properties must be for the same stream set as the cohort stream_name. Nulls are excluded unless explicitly requested with _null: true. Example: [{"property": "total", "gte": 50}]
stream_namestring- The name field of the stream from which to build this cohort. Example: orders.
traitsarray- List of traits to filter cohort membership. Example: [{"name": "plan_tier", "eq": "gold"}]
faraday_dataset_createCreate a dataset that ingests data from an upload or a connection and maps its columns to identities, events (streams) and traits.WriteCreate Dataset
Create a dataset that ingests data from an upload or a connection and maps its columns to identities, events (streams) and traits. Returns the dataset with id and status. Use faraday_dataset_create after uploading a CSV or creating a connection.
Inputs
identity_setsobjectrequired- (Parameters used to POST a new value of the IdentitySets type.) A mapping of {identity set name} (ex. shipping) -> {identity set object}. Describes all the logical groupings of personally-identifiable information present in the dataset. Identity set objects map canonical names to dataset column names. The following keys are supported: * email * email_hash * email_hash_base64 * phone * phone_hash_base64 * person_full_name * person_last_name * person_first_name * person_date_of_birth_postcode_hash_base64 * house_number_and_street * city * state * postcode * freeform_address * date_of_birth All k. Example: {"customer": {"email": "email", "person_first_name": "first_name", "person_last_name": "last_name", "postcode": "zip"}}
namestringrequired- Human-readable name, unique in the account. Example: Customers.
optionsobjectrequired- Dataset connection options. Example: {"type": "hosted_csv", "upload_directory": "customers"}
connection_idstring- If this is a "retrieve" dataset, the UUID of a connection - see /connections for more detail. Only a subset of connection types can be configured for dataset ingestion - see the list available in options. Note that if a connection_id is specified, options must also be specified. Example: 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e.
incremental_columnstring- A column specifying a date associated with a record. Ideally incremental_column SHOULD be set to make data loading more efficient. Ideally ALSO set upsert_columns to ensure that data is not duplicated in the dataset. After each ingestion, the most recent value from incremental_column on any record will be recorded, and during future ingestions, any records with a value older than incremental_column will be ignored. Example: updated_at.
output_to_streamsobject- (Parameters used to POST a new value of the OutputToStreams type.) Describes how to transform the dataset into one or more streams. Streams typically represent events. They can have multiple dataset sources and each dataset can be used to populate multiple streams. The shape of this parameter is a mapping of stream names to stream output columns, given by a data_map object. Ex: "output_to_streams": { "orders": { /streams/{stream_id_or_name} . A data_map object can have any keys, but it is recommended to include the reserved datetime key as this will improve modeling. Each key of the data_map. Example: {"orders": {"datetime": "order_date", "value": "total"}}
output_to_traitsobject- (Parameters used to POST a new value of the OutputToTraits type.) A mapping of trait name to trait definition, where the key is what the trait will be called in Faraday's system. Traits are characteristics about people, that are unrelated to particular events. When specifying or modifying this parameter, bulk trait declarations specified with output_all_columns_as_traits must be null. There is an option to provide either a static value or a column name for each trait. Please provide one or the other. Example: {"plan_tier": {"column_name": "tier"}}
previewboolean- A dataset in preview mode will only detect columns and produce a data preview, but not ingest the data. Defaults to undefined, which is equivalent to false. Example: false.
privacystring- Marks this dataset as a privacy list. Every person matched in it is kept out of what the account delivers. Omit for an ordinary dataset. - suppress - do not contact. Matched people can still be members of cohorts and be used to train outcomes, persona sets and recommenders, but are left out of the output of every scope and target in the account. Use for unsubscribes, do-not-mail and do-not-call requests, and opt-outs of sale. - delete - do not use. Matched people are also removed from the account's other datasets and from its cohorts, so they are not used for modeling either, and are left out. Example: suppress.one of
suppressdelete reference_key_columnsarray- The names of columns that reference IDs from an external system. Setting this enables export of data via /targets that is keyed on this field. Example: ["customer_id"]
upsert_columnsarray- Also known as the "primary key" of the dataset. A column or set of columns that uniquely identify an input row. Ideally upsert_columns SHOULD be set so that data is not duplicated in the dataset. Ideally ALSO set incremental_column to make data loading more efficient. If multiple rows are ingested with identical values in the columns specified by upsert_columns, the newest will be used. If neither upsert_columns nor incremental_column are specified, each unique row will be ingested once. Example: ["customer_id"]
faraday_dataset_updateUpdate a dataset's configuration; only the fields you send change.WriteUpdate Dataset
Update a dataset's configuration; only the fields you send change. Returns the updated dataset. Use faraday_dataset_update to change column mappings or options.
Inputs
dataset_idstringrequired- UUID of the dataset. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
identity_setsobject- (Parameters used to PATCH the IdentitySets type.) A mapping of {identity set name} (ex. shipping) -> {identity set object}. Describes all the logical groupings of personally-identifiable information present in the dataset. Identity set objects map canonical names to dataset column names. The following keys are supported: * email * email_hash * email_hash_base64 * phone * phone_hash_base64 * person_full_name * person_last_name * person_first_name * person_date_of_birth_postcode_hash_base64 * house_number_and_street * city * state * postcode * freeform_address * date_of_birth All keys must corre. Example: {"customer": {"email": "email", "person_first_name": "first_name", "person_last_name": "last_name", "postcode": "zip"}}
incremental_columnstring- A column specifying a date associated with a record. Ideally incremental_column SHOULD be set to make data loading more efficient. Ideally ALSO set upsert_columns to ensure that data is not duplicated in the dataset. After each ingestion, the most recent value from incremental_column on any record will be recorded, and during future ingestions, any records with a value older than incremental_column will be ignored. Example: updated_at.
namestring- Human-readable name, unique in the account. Example: Customers.
optionsobject- Dataset connection options. Example: {"type": "hosted_csv", "upload_directory": "customers"}
output_to_streamsobject- Output To Streams. Example: {"orders": {"datetime": "order_date", "value": "total"}}
output_to_traitsobject- Output To Traits. Example: {"plan_tier": {"column_name": "tier"}}
previewboolean- A dataset in preview mode will only detect columns and produce a data preview, but not ingest the data. Defaults to undefined, which is equivalent to false. Example: false.
privacystring- Marks this dataset as a privacy list. Every person matched in it is kept out of what the account delivers. Omit for an ordinary dataset. - suppress - do not contact. Matched people can still be members of cohorts and be used to train outcomes, persona sets and recommenders, but are left out of the output of every scope and target in the account. Use for unsubscribes, do-not-mail and do-not-call requests, and opt-outs of sale. - delete - do not use. Matched people are also removed from the account's other datasets and from its cohorts, so they are not used for modeling either, and are left out. Example: suppress.
reference_key_columnsarray- The names of columns that reference IDs from an external system. Setting this enables export of data via /targets that is keyed on this field. Example: ["customer_id"]
upsert_columnsarray- Also known as the "primary key" of the dataset. A column or set of columns that uniquely identify an input row. Ideally upsert_columns SHOULD be set so that data is not duplicated in the dataset. Ideally ALSO set incremental_column to make data loading more efficient. If multiple rows are ingested with identical values in the columns specified by upsert_columns, the newest will be used. If neither upsert_columns nor incremental_column are specified, each unique row will be ingested once. Example: ["customer_id"]
faraday_forecast_createCreate a forecast that predicts the summed value of a stream property within a horizon after each entry event, for example 12-month revenue after signup.WriteCreate Forecast
Create a forecast that predicts the summed value of a stream property within a horizon after each entry event, for example 12-month revenue after signup. Returns the forecast with id and status. Use faraday_forecast_create for lifetime value.
Inputs
entry_stream_namestringrequired- Name of the stream whose events are the entries. Each event starts a horizon at its own date. May be the same stream as stream_name. Without entry_key_property_name, each person's first event on this stream is their entry. Example: signups.
horizonobjectrequired- (Parameters used to POST a new value of the ForecastHorizon type.) How far past each entry's event the forecast reaches. Example: {"max_days": 365}
namestringrequired- Human-readable name, unique in the account. Example: Customers.
stream_namestringrequired- Name of the stream whose events carry the value to forecast. Example: orders.
stream_property_namestringrequired- Name of the numeric property of stream_name to sum. Negative values are summed as they are, so refunds recorded as negative events net correctly. The forecast is in the unit the stream property holds: a dataset column mapped with the currency_cents or currency_dollars format reaches the stream in the currency's major unit, so the forecast is in dollars; a column mapped with no format keeps its own unit. A referenced-mode target can also deliver each row's value in cents (fdy_forecast_ _entry_value_cents), the major-unit value times 100 as an integer. Example: product_sku.
currencystring- The ISO 4217 code of the currency the forecast is expressed in. With currency_property_name, events in other currencies are converted into it at a reference rate; without, values are summed as recorded. Must be a currency with a reference rate when currency_property_name is set. Example: USD.
eligible_cohort_idstring- Optional cohort that restricts which entries the model learns from: when set, only entries whose person is currently a member of the cohort are used for training. It does not restrict scoring. Omit it to train on every entry. Example: 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e.
stream_conditionsarray- Conditions on the properties of stream_name. When set, only events that satisfy every condition count toward the value; when omitted, every event on the stream counts. Each property must exist on stream_name. The conditions are evaluated exactly as a cohort's stream conditions are. An event whose property is null satisfies _nin, so {"property": "status", "_nin": ["failed"]} keeps events with no status; add _nnull: true to the condition to drop them. Every other operator excludes null values, and _null: true selects them. Example: [{"property": "total", "gte": 50}]
faraday_outcome_createCreate an outcome: a model predicting who in an eligible cohort will join an attainment cohort.WriteCreate Outcome
Create an outcome: a model predicting who in an eligible cohort will join an attainment cohort. Returns the outcome with id and status; it builds in the background. Use faraday_outcome_create for propensity, churn or conversion scores.
Inputs
attainment_cohort_idstringrequired- A cohort of people who have attained the desired outcome (for example, if predicting transition from prospect to customer, the attainment cohort should be existing customers). Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
namestringrequired- Human-readable name, unique in the account. Example: Customers.
attrition_cohort_idstring- A cohort of counterexamples - people who have clearly failed to attain the outcome, as opposed to simply being indeterminate. This cohort is optional. Example: 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e.
bias_mitigationobject- The strategy to be applied to gender and/or age to mitigate or reverse the bias found in the attainment population. Though the spec appears you can combine different mitigation strategies per dimension of concern (age=equity, gender=equality), API runtime validation will prevent it for now. Later we may support this so the spec is designed for future proofing. Note: age=none, gender=equity is allowed. Mitigation on age or gender needs that field, so an outcome cannot also block fig/age or fig/gender, or a category that contains it, for a dimension whose strategy is not none. Example: {"age": "equality", "gender": "equality"}
eligible_cohort_idstring- A cohort of people who could attain or attrite the desired outcome (for example, if predicting transition from prospect to customer, the eligible cohort should be prospects). If no eligible cohort is specified, the model will use the US population as the eligible cohort. Example: 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e.
feature_blocklistarray- The name of a field or category of fields which should not be considered for this Outcome. Should be used primarily for the purposes of Responsible AI. Omitted from responses when the list is empty. Deprecated: use predictors.blocked instead. This list and predictors.blocked are stored apart: a change to one does not change the other. A request cannot send both this list and predictors.blocked.traits, attributes or categories. Example: ["fdy/age"]
prediction_modestring- Defaults to auto, which enables dynamic modeling if possible. The other option is static, which disables dynamic modeling. Dynamic modeling considers chronology and uses advanced feature engineering whenever possible. You may want to disable dynamic prediction if chronology could confuse your use case, or if advised by Faraday staff. Example: auto.one of
autostatic previewboolean- An outcome in preview mode will not build until preview is turned off. Example: false.
faraday_outcome_updateUpdate an outcome; only the fields you send change.WriteUpdate Outcome
Update an outcome; only the fields you send change. Returns the updated outcome. Use faraday_outcome_update to rename it or turn off preview.
Inputs
outcome_idstringrequired- UUID of the outcome. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
bias_mitigationobject- The strategy to be applied to gender and/or age to mitigate or reverse the bias found in the attainment population. Though the spec appears you can combine different mitigation strategies per dimension of concern (age=equity, gender=equality), API runtime validation will prevent it for now. Later we may support this so the spec is designed for future proofing. Note: age=none, gender=equity is allowed. Mitigation on age or gender needs that field, so an outcome cannot also block fig/age or fig/gender, or a category that contains it, for a dimension whose strategy is not none. Example: {"age": "equality", "gender": "equality"}
feature_blocklistarray- The name of a field or category of fields which should not be considered for this Outcome. Should be used primarily for the purposes of Responsible AI. Omitted from responses when the list is empty. Deprecated: use predictors.blocked instead. This list and predictors.blocked are stored apart: a change to one does not change the other. A request cannot send both this list and predictors.blocked.traits, attributes or categories. Example: ["fdy/age"]
namestring- Human-readable name, unique in the account. Example: Customers.
prediction_modestring- Defaults to auto, which enables dynamic modeling if possible. The other option is static, which disables dynamic modeling. Dynamic modeling considers chronology and uses advanced feature engineering whenever possible. You may want to disable dynamic prediction if chronology could confuse your use case, or if advised by Faraday staff. Example: auto.
previewboolean- An outcome in preview mode will not build until preview is turned off. Example: false.
faraday_persona_set_createCreate a persona set that clusters a cohort into personas.WriteCreate Persona Set
Create a persona set that clusters a cohort into personas. Returns the persona set with id and status. Use faraday_persona_set_create to segment customers.
Inputs
cohort_idstringrequired- The cohort to organize into personas. Personas are built from cohort members matched at the individual level. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
namestringrequired- Human-readable name, unique in the account. Example: Customers.
clustering_dimensionsobject- The dimensions the clustering system should consider when discovering the personas in a persona set. By default, Faraday will consider a fixed set of broadly effective dimensions when discovering your personas. Advanced users can override our recommendation and specify their own. Note that the system may consider additional dimensions you do not list in order to improve performance. Each group is independent and any combination may be provided. The groups available to an account depend on whether it has an identity graph feature store set. This supersedes the deprecated modeling_fields, modeli. Example: {"attributes": ["fdy/age", "fdy/income"]}
number_of_clustersinteger- Specify the exact number of clusters (i.e. personas) there should be in the persona set. By default, the optimal value for this parameter is determined automatically. Setting this requires external knowledge and should only be done when the use-case necessitates a specific number of clusters. Example: 4.
previewboolean- A persona set in preview mode will not build until preview is turned off. Example: false.
faraday_place_createCreate a place from addresses or a GeoJSON geometry.WriteCreate Place
Create a place from addresses or a GeoJSON geometry. Returns the place. Use faraday_place_create to target an area such as a store's trade zone.
Inputs
namestringrequired- Human-readable name, unique in the account. Example: Customers.
addressesarray- Addresses. Example: [{"house_number_and_street": "123 Main Street", "city": "Anytown", "state": "VT", "postcode": "05401"}]
geojsonobject- A GeoJSON Geometry, as defined in the [GeoJSON specification](https://www.rfc-editor.org/rfc/rfc7946#section-3.1) The longitude and latitude units of this geometry are expected to be in decimal degrees, using the WGS84 coordinate reference system, also known by the SRID 4326. https://www.rfc-editor.org/rfc/rfc7946#section-4. Example: {"type": "Point", "coordinates": [-73.2121, 44.4759]}
faraday_place_updateUpdate a place's name, addresses or geometry.WriteUpdate Place
Update a place's name, addresses or geometry. Returns the updated place. Use faraday_place_update to redraw an area.
Inputs
place_idstringrequired- UUID of the place. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
addressesarray- Addresses. Example: [{"house_number_and_street": "123 Main Street", "city": "Anytown", "state": "VT", "postcode": "05401"}]
geojsonobject- A GeoJSON Geometry, as defined in the [GeoJSON specification](https://www.rfc-editor.org/rfc/rfc7946#section-3.1) The longitude and latitude units of this geometry are expected to be in decimal degrees, using the WGS84 coordinate reference system, also known by the SRID 4326. https://www.rfc-editor.org/rfc/rfc7946#section-4. Example: {"type": "Point", "coordinates": [-73.2121, 44.4759]}
namestring- Human-readable name, unique in the account. Example: Customers.
faraday_recommender_createCreate a recommender that predicts the next value of a stream property, such as the next product a customer buys.WriteCreate Recommender
Create a recommender that predicts the next value of a stream property, such as the next product a customer buys. Returns the recommender with id and status. Use faraday_recommender_create for next-best-product.
Inputs
namestringrequired- Human-readable name, unique in the account. Example: Customers.
stream_namestringrequired- Name of the stream to use for recommendations. Example: orders.
stream_property_namestringrequired- Name of the stream property. Example: product_sku.
previewboolean- A recommender in preview mode will not build until preview is turned off. Example: false.
faraday_scope_createCreate a scope: the population to score and the predictions (outcomes, persona sets, recommenders, cohorts) to include.WriteCreate Scope
Create a scope: the population to score and the predictions (outcomes, persona sets, recommenders, cohorts) to include. Returns the scope with id and status. Use faraday_scope_create before faraday_target_create.
Inputs
namestringrequired- Human-readable name, unique in the account. Example: Customers.
payloadobjectrequired- (Parameters used to POST a new value of the ScopePayload type.) The data to include for each person in this scope. Example: {"outcome_ids": ["4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c"]}
populationobjectrequired- (Parameters used to POST a new value of the ScopePopulation type.) The people to include in a scope. Leave cohort_ids empty to include the entire US population. Example: {"cohort_ids": ["4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c"]}
previewbooleanrequired- A preview scope provides only a limited number of output records, but it is not billed. Example: false.
insightsboolean- Include this scope's predictions in the account's Insights, as a table of their own that GET /insights lists. Turning it on requires the plan feature insights.scopes_enabled. A preview scope can be opted in, but its table is left out of Insights until preview is turned off and the scope's next full build finishes. Example: false.
faraday_scope_force_updateRebuild a scope and its dependencies now.WriteForce Update Scope
Rebuild a scope and its dependencies now. Returns no content when queued. Use faraday_scope_force_update after changing upstream data.
Inputs
scope_idstringrequired- UUID of the scope. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_scope_updateUpdate a scope; only the fields you send change.WriteUpdate Scope
Update a scope; only the fields you send change. Returns the updated scope. Use faraday_scope_update to change its population or payload, or turn off preview.
Inputs
scope_idstringrequired- UUID of the scope. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
insightsboolean- Include this scope's predictions in the account's Insights, as a table of their own that GET /insights lists. Turning it on requires the plan feature insights.scopes_enabled. A preview scope can be opted in, but its table is left out of Insights until preview is turned off and the scope's next full build finishes. Example: false.
namestring- Human-readable name, unique in the account. Example: Customers.
payloadobject- (Parameters used to PATCH the ScopePayload type.) The data to include for each person in this scope. Example: {"outcome_ids": ["4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c"]}
populationobject- (Parameters used to PATCH the ScopePopulation type.) The people to include in a scope. Leave cohort_ids empty to include the entire US population. Example: {"cohort_ids": ["4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c"]}
previewboolean- A preview scope provides only a limited number of output records, but it is not billed. Example: false.
faraday_target_createCreate a target that delivers a scope's results: a hosted CSV, a connection, or the lookup API (mode identified).WriteCreate Target
Create a target that delivers a scope's results: a hosted CSV, a connection, or the lookup API (mode identified). Returns the target with id and status. Use faraday_target_create after faraday_scope_create.
Inputs
namestringrequired- Human-readable name, unique in the account. Example: Customers.
optionsobjectrequired- The export target configuration options. These vary by connection type. Example: {"type": "hosted_csv", "upload_directory": "customers"}
representationobjectrequired- Choose how the scopes's output should be formatted for this target. The following **modes** are available: **aggregated** * This option will produce one row per geographical area. * This option is best for geo-targeted ad campaigns. **hashed** * Faraday's name, physical address, and email is emitted in hashed form. Data is randomly ordered to prevent re-identification. All payload columns are emitted except raw propensity scores and attributes. * This option facilitates digital acquisition use cases. **identified** * All identifiable information specified by identity_sets in source data is emi. Example: {"mode": "identified"}
scope_idstringrequired- The UUID of a scope - see /scopes for more detail. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
connection_idstring- If this is a replication (externally-hosted) target, the UUID of a connection - see /connections for more detail. If this is not a replication target, omit this parameter. Example: 9b1c2d3e-4f5a-4b6c-8d7e-0f1a2b3c4d5e.
custom_structurearray- By default, targets include all columns in the target preview , with no name changes. Users may use this parameter to specify their own set of "structure transformations" to override the default selection, order, and name of exported columns. The shape of this parameter is an array of objects where the order of the columns to export is given by the order of the array. Each item represents a 1:1 mapping of scope input column to target output column. Only those columns specified here are emitted in the target output. Example: [{"scope_col": "fdy_outcome_4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c_propensity_probability", "export_col": "propensity"}]
filterobject- (Parameters used to POST a new value of the TargetFilter type.) Filter the rows exported in a target using the scope payload elements. - **Deprecated:** To filter by outcome scores, use outcome_score. - To filter by outcome probability, use outcome_probability. - To filter by outcome percentile, use outcome_percentile. - To filter by persona set persona id, use persona. - To filter by cohort membership, use cohort_membership. The cohort does not need to be in the scope payload. - To filter by trait, use trait. - To filter by attribute, use attribute. - To filter by recommender uncalibrated pro. Example: {"outcome_percentile": [{"outcome_id": "4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c", "gte": 90}]}
human_readableboolean- By default, column names are exported in a machine-readable format with underscored uuids. Setting this to true replaces ids with literates in the exported column names. Example: true.
limitobject- Restrict the number of rows exported in a target. - To apply an absolute row limit, use row_count. - **Deprecated:** To filter by percentile scores, use percentile (use filter outcome_percentile instead). Target limits are not supported for targets with options.type = "lookup_api". Example: {"method": "row_count", "threshold": 1000}
faraday_target_force_updateRe-export a target now.WriteForce Update Target
Re-export a target now. Returns no content when queued. Use faraday_target_force_update to refresh an export.
Inputs
target_idstringrequired- UUID of the target. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_target_lookupScore one person in real time with a lookup-API target, matching them by PII.WriteLook Up Person on Target
Score one person in real time with a lookup-API target, matching them by PII. Returns the person's predictions (scores, persona, recommendations) from the target's scope. Use faraday_target_lookup with an identified-mode target; provide name plus address, or email, or phone.
Inputs
target_idstringrequired- UUID of the target. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
citystring- City. Example: Anytown.
emailstring- Email address. Example: john_doe@example.com.
email_hashstring- Lowercase hex SHA-256 of the lowercased email. Example: ea7047caf2a60b1c20c6c13b12a47e4e08610736f2062b0ae67c266f7a9516c9.
house_number_and_streetstring- Street address. Example: 123 Main Street.
person_first_namestring- First name. Example: John.
person_last_namestring- Last name. Example: Doe.
phonestring- Phone number. Example: 8025550101.
postcodestring- Five-digit ZIP code. Example: 05401.
statestring- State name or code. Example: VT.
faraday_target_updateUpdate a target; only the fields you send change.WriteUpdate Target
Update a target; only the fields you send change. Returns the updated target. Use faraday_target_update to change its filter, limit or structure.
Inputs
target_idstringrequired- UUID of the target. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
custom_structurearray- By default, targets include all columns in the target preview , with no name changes. Users may use this parameter to specify their own set of "structure transformations" to override the default selection, order, and name of exported columns. The shape of this parameter is an array of objects where the order of the columns to export is given by the order of the array. Each item represents a 1:1 mapping of scope input column to target output column. Only those columns specified here are emitted in the target output. Example: [{"scope_col": "fdy_outcome_4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c_propensity_probability", "export_col": "propensity"}]
filterobject- Filter. Example: {"outcome_percentile": [{"outcome_id": "4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c", "gte": 90}]}
human_readableboolean- By default, column names are exported in a machine-readable format with underscored uuids. Setting this to true replaces ids with literates in the exported column names. Example: true.
limitobject- Limit. Example: {"method": "row_count", "threshold": 1000}
namestring- Human-readable name, unique in the account. Example: Customers.
optionsobject- The export target configuration options. These vary by connection type. Example: {"type": "hosted_csv", "upload_directory": "customers"}
representationobject- Choose how the scopes's output should be formatted for this target. The following **modes** are available: **aggregated** * This option will produce one row per geographical area. * This option is best for geo-targeted ad campaigns. **hashed** * Faraday's name, physical address, and email is emitted in hashed form. Data is randomly ordered to prevent re-identification. All payload columns are emitted except raw propensity scores and attributes. * This option facilitates digital acquisition use cases. **identified** * All identifiable information specified by identity_sets in source data is emi. Example: {"mode": "identified"}
faraday_trait_createCreate a trait that datasets can populate.WriteCreate Trait
Create a trait that datasets can populate. Returns the trait. Use faraday_trait_create before mapping a dataset column to it.
Inputs
namestringrequired- Human-readable name, unique in the account. Example: Customers.
descriptionstring- Information about this field. Example: Customer plan tier.
literatestring- A more human-consumable version of the name of this field. Example: Plan tier.
lookup_tableobject- A mapping of the input values used in modeling, to how they should be displayed in reports. Example: {"gold": "Gold plan"}
statistical_typestring- A string describing the nature of data represented by the trait. categorical_nominal: the field contains one value of an unordered bounded set. Example: "preferred_channel" — one of "email", "sms", "direct_mail". categorical_ordinal: the field contains one value of an ordered bounded set. Example: "spending_tier" — one of "low", "medium", "high", "premium". multicategorical_nominal: the field contains one or more values of an unordered bounded set. Example: "interests" — "outdoors", "travel", "fitness". continuous_ordinal: the field contains numeric values with a natural ordering. Example: "li.one of
categoricalmulticategoricalordinalnominalcontinuous_ordinalcategorical_nominalmulticategorical_nominalcategorical_ordinalbinarycountintervalratio unitstring- For numeric types, in what units is the data stored. Example: USD.
faraday_cohort_deleteDelete a cohort.DestructiveDelete Cohort
Delete a cohort. Returns no content on success. Use faraday_cohort_delete to remove it; archive it in the app instead if other resources depend on it.
- Idempotent
Inputs
cohort_idstringrequired- UUID of the cohort. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_dataset_deleteDelete a dataset.DestructiveDelete Dataset
Delete a dataset. Returns no content on success. Use faraday_dataset_delete to remove it; archive it in the app instead if other resources depend on it.
- Idempotent
Inputs
dataset_idstringrequired- UUID of the dataset. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_outcome_deleteDelete a outcome.DestructiveDelete Outcome
Delete a outcome. Returns no content on success. Use faraday_outcome_delete to remove it; archive it in the app instead if other resources depend on it.
- Idempotent
Inputs
outcome_idstringrequired- UUID of the outcome. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_scope_deleteDelete a scope.DestructiveDelete Scope
Delete a scope. Returns no content on success. Use faraday_scope_delete to remove it; archive it in the app instead if other resources depend on it.
- Idempotent
Inputs
scope_idstringrequired- UUID of the scope. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
faraday_target_deleteDelete a target.DestructiveDelete Target
Delete a target. Returns no content on success. Use faraday_target_delete to remove it; archive it in the app instead if other resources depend on it.
- Idempotent
Inputs
target_idstringrequired- UUID of the target. Example: 4f8a2c1e-7b3d-4e9a-8c6f-1d2e3f4a5b6c.
No tools match.