Create outcome
https://api.faraday.ai/v1/outcomesAdd a new outcome (defined as a prediction of how likely individuals are to transition from one cohort to another)
Authentication
Provide your API key in the Authorization header. You can find your API key in the Settings page of the dashboard.
Authorization: Bearer YOUR_TOKENBody
The definition of the new outcome
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).
"5bf9aa70-7bf1-4ef1-a131-8c84441be231"attrition_cohort_idstring<uuid>A cohort of counterexamples - people who have clearly failed to attain the outcome, as opposed to simply being indeterminate. This cohort is optional.
"3a6878ab-525f-418b-bea5-e9b8fd2dde2a"bias_mitigationobjectThe 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 dimensi...
eligible_cohort_idstring<uuid>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 ...
"d7a8b7df-4bb3-4f55-af9f-7f2138d3796d"feature_blocklistarray[string]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.
["fig/gender"]Human-readable label for this outcome. Each outcome must have a unique name.
"Lead Conversion"^(?!\s*$).+prediction_modestringDefaults 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 w...
auto, staticpredictorsobject(Parameters used to POST a new value of the OutcomePredictors type.)
Provides control over the features used during modeling to predict an outcome.
Responses
201The new outcome
archived_atstring<date-time>If not null, this resource will no longer receive updates, but will still be visable.
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).
"5bf9aa70-7bf1-4ef1-a131-8c84441be231"attainment_cohort_namestringHuman-readable label of the attainment cohort. See /cohorts/{attainment_cohort_id} to edit the attainment cohort or view additional details.
"customers"attrition_cohort_idstring<uuid>A cohort of counterexamples - people who have clearly failed to attain the outcome, as opposed to simply being indeterminate. This cohort is optional.
"3a6878ab-525f-418b-bea5-e9b8fd2dde2a"attrition_cohort_namestringHuman-readable label of the attrition cohort. See /cohorts/{attrition_cohort_id} to edit the attrition cohort or view additional details.
"unqualified leads"bias_mitigationobjectThe 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 dimensi...
When this resource was created.
eligible_cohort_idstring<uuid>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 ...
"d7a8b7df-4bb3-4f55-af9f-7f2138d3796d"eligible_cohort_namestringHuman-readable label of the eligibility cohort. See /cohorts/{eligible_cohort_id} to edit the eligible cohort or view additional details.
"leads"feature_blocklistarray[string]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.
["fig/gender"]A unique ID for this resource.
"b80217ae-7628-4c66-8a19-5bf452495c39"last_read_input_atstring<date-time>The last time this resource's input was read.
last_updated_config_atstring<date-time>The last time this resource's configuration was updated. If this is more recent than last_updated_output_at, the resource will be rebuilt.
last_updated_output_atstring<date-time>The last time this resource successfully built.
lift_valuenumberAverage of lift over random at average conversion rate (r), (0.75 * r), (0.5 * r), (0.25 * r).
1.425Human-readable label for this outcome. Each outcome must have a unique name.
"Lead Conversion"^(?!\s*$).+prediction_modestringDefaults 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 w...
auto, staticpredictorsobjectProvides control over the features used during modeling to predict an outcome.
report_urlstringURL of an HTML report containing information such as the objective of the model, performance, and important features.
roc_aucnumberThe area under the receiver operating characteristic curve. Typically, the higher the ROC AUC, the better the model.
0.75The current state of this resource and any updates.
"pending"new, starting, running, ready, errorstatus_changed_atstring<date-time>When the status of this resource was last updated.
status_errorstringIf this resource has status == "error", this will contain an error message.
When this resource was last updated.
400The request was invalid.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICTA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
401No API key was supplied.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICTA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
403Access to this resource was forbidden.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICTA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
404The requested resource ID was not found.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICTA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
409The request was formatted correctly, but conflicted with an existing resource.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICTA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
500An internal server error occurred.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICTA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
Tags
Test request
Request snippet
curl -X POST 'https://api.faraday.ai/v1/outcomes' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"attainment_cohort_id": "5bf9aa70-7bf1-4ef1-a131-8c84441be231",
"attrition_cohort_id": "3a6878ab-525f-418b-bea5-e9b8fd2dde2a",
"bias_mitigation": {
"age": "none",
"gender": "none"
},
"eligible_cohort_id": "d7a8b7df-4bb3-4f55-af9f-7f2138d3796d",
"feature_blocklist": [
"fig/gender"
],
"name": "Lead Conversion",
"prediction_mode": "auto",
"predictors": {
"blocked": {
"providers": [
"self"
]
}
},
"preview": true
}'Example response
{
"archived_at": "2024-01-01T12:00:00Z",
"attainment_cohort_id": "5bf9aa70-7bf1-4ef1-a131-8c84441be231",
"attainment_cohort_name": "customers",
"attrition_cohort_id": "3a6878ab-525f-418b-bea5-e9b8fd2dde2a",
"attrition_cohort_name": "unqualified leads",
"bias_mitigation": {
"age": "none",
"gender": "none"
},
"created_at": "2024-01-01T12:00:00Z",
"eligible_cohort_id": "d7a8b7df-4bb3-4f55-af9f-7f2138d3796d",
"eligible_cohort_name": "leads",
"feature_blocklist": [
"fig/gender"
],
"id": "b80217ae-7628-4c66-8a19-5bf452495c39",
"last_read_input_at": "2024-01-01T12:00:00Z",
"last_updated_config_at": "2024-01-01T12:00:00Z",
"last_updated_output_at": "2024-01-01T12:00:00Z",
"lift_value": 1.425,
"name": "Lead Conversion",
"prediction_mode": "auto",
"predictors": {
"blocked": {
"providers": [
"self"
]
}
},
"preview": true,
"report_url": "string",
"resource_type": "outcomes",
"roc_auc": 0.75,
"status": "pending",
"status_changed_at": "2024-01-01T12:00:00Z",
"status_error": "string",
"updated_at": "2024-01-01T12:00:00Z"
}