Create forecast

posthttps://api.faraday.ai/v1/forecasts
This endpoint is experimental and may change without notice.

Add a new forecast.

This feature is experimental and subject to change. To enable this feature, contact your account manager.

Authentication

Bearer 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_TOKEN

Body

The definition of the new forecast

currencystring

The ISO 4217 code of the currency the forecast is expressed in. Values are summed as recorded; nothing is excluded or converted.

Example: "USD"
Match pattern: ^[A-Z]{3}$
currency_property_namestring

Name of the property of stream_name holding each event's currency code. Informational: no event is excluded or converted because of its currency; it lets the forecast report how much value is recorded in currencies other than currency.

Example: "currency"
deduction_property_namestring

Name of a numeric property of stream_name whose absolute value is subtracted from stream_property_name on the same event before summing, for refunds that are recorded on the original event rather ...

Example: "amount_refunded"
eligible_cohort_idstring<uuid>

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.

entry_key_property_namestring

Name of a property present on both entry_stream_name and stream_name that identifies the entry, such as a subscription or order id. When set, each distinct value is its own entry and value is attr...

Example: "subscription_id"
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: "stripe_subscriptions"
horizonobjectrequired

(Parameters used to POST a new value of the ForecastHorizon type.)

How far past each entry's event the forecast reaches.

Additional properties: not allowed
Properties of object
max_daysintegerrequired

Length of the horizon in days, measured from the entry event and inclusive of the day of the event.

Example: 456
Minimum value: 1
namestringrequired

Human-readable label for this forecast. Unique within the account, case-insensitive.

Example: "Subscription value, 456 days"
Match pattern: ^(?!\s*$).+
Maximum characters: 64
predictorsobject

(Parameters used to POST a new value of the ForecastPredictors type.)

Provides control over the data used during modeling for a forecast.

Additional properties: not allowed
Properties of object
max_observation_datestring<date>

Train and score as if no data after this date existed. If not set, the freshest available data is used.

stream_conditionsarray[object]

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 ...

Items of array[object]
_eqstring

Equal to

_gtnumber

Greater than. Not allowed on datetime or other properties of type date; use _on_or_after instead.

_gtenumber

Greater than or equal to. Not allowed on datetime or other properties of type date; use _on_or_after instead.

_inarray[string]

Value is one of

_ltnumber

Less than. Not allowed on datetime or other properties of type date; use _on_or_before instead.

_ltenumber

Less than or equal to. Not allowed on datetime or other properties of type date; use _on_or_before instead.

_matchesstring

Value contains a match to the regex (re2) expression provided. For an exact regex match, use the ^ and $ characters as specified by the (re2 documentation)[https://github.com/google/re2/wiki/Syntax].

_ninarray[string]

Value is not one of

_nnullboolean

Value is not null

_nullboolean

Value is null (nulls are otherwise excluded)

_on_or_afterstring<date>

On or after this day, given as YYYY-MM-DD. Values are compared by calendar day, ignoring time of day, so events at any time on this day match. Only for datetime and other properties of type date...

_on_or_beforestring<date>

On or before this day, given as YYYY-MM-DD. Values are compared by calendar day, ignoring time of day, so events at any time on this day match. Only for datetime and other properties of type `date...

optionalboolean

Optional stream conditions are unioned together, when combined they define cohorts that meet either stream condition. At least one optional condition must be satisfied.

propertystringrequired

Stream property name.

Maximum characters: 256
stream_namestringrequired

Name of the stream whose events carry the value to forecast.

Example: "stripe_charges"
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 stream property's format (currency_cents or `c...

Example: "amount"

Responses

201The new forecast
archived_atstring<date-time>

If not null, this resource will no longer receive updates, but will still be visable.

created_atstring<date-time>required

When this resource was created.

currencystring

The ISO 4217 code of the currency the forecast is expressed in. Values are summed as recorded; nothing is excluded or converted.

Example: "USD"
Match pattern: ^[A-Z]{3}$
currency_property_namestring

Name of the property of stream_name holding each event's currency code. Informational: no event is excluded or converted because of its currency; it lets the forecast report how much value is recorded in currencies other than currency.

Example: "currency"
deduction_property_namestring

Name of a numeric property of stream_name whose absolute value is subtracted from stream_property_name on the same event before summing, for refunds that are recorded on the original event rather ...

Example: "amount_refunded"
eligible_cohort_idstring<uuid>

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.

eligible_cohort_namestring

Human-readable label of the eligible cohort. See /cohorts/{eligible_cohort_id} to edit the eligible cohort or view additional details.

entry_key_property_namestring

Name of a property present on both entry_stream_name and stream_name that identifies the entry, such as a subscription or order id. When set, each distinct value is its own entry and value is attr...

Example: "subscription_id"
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: "stripe_subscriptions"
horizonobjectrequired

How far past each entry's event the forecast reaches.

Additional properties: not allowed
Properties of object
max_daysintegerrequired

Length of the horizon in days, measured from the entry event and inclusive of the day of the event.

Example: 456
Minimum value: 1
idstring<uuid>required

A unique ID for this resource.

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.

namestringrequired

Human-readable label for this forecast. Unique within the account, case-insensitive.

Example: "Subscription value, 456 days"
Match pattern: ^(?!\s*$).+
Maximum characters: 64
predictorsobject

Provides control over the data used during modeling for a forecast.

Additional properties: not allowed
Properties of object
max_observation_datestring<date>

Train and score as if no data after this date existed. If not set, the freshest available data is used.

report_urlstring

URL of an HTML report on the forecast's performance.

resource_typestringrequired

The type of this resource.

statusstringrequired

The current state of this resource and any updates.

Example: "pending"
Allowed values: new, starting, running, ready, error
status_changed_atstring<date-time>

When the status of this resource was last updated.

status_errorstring

If this resource has status == "error", this will contain an error message.

stream_conditionsarray[object]

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 ...

Items of array[object]
_eqstring

Equal to

_gtnumber

Greater than. Not allowed on datetime or other properties of type date; use _on_or_after instead.

_gtenumber

Greater than or equal to. Not allowed on datetime or other properties of type date; use _on_or_after instead.

_inarray[string]

Value is one of

_ltnumber

Less than. Not allowed on datetime or other properties of type date; use _on_or_before instead.

_ltenumber

Less than or equal to. Not allowed on datetime or other properties of type date; use _on_or_before instead.

_matchesstring

Value contains a match to the regex (re2) expression provided. For an exact regex match, use the ^ and $ characters as specified by the (re2 documentation)[https://github.com/google/re2/wiki/Syntax].

_ninarray[string]

Value is not one of

_nnullboolean

Value is not null

_nullboolean

Value is null (nulls are otherwise excluded)

_on_or_afterstring<date>

On or after this day, given as YYYY-MM-DD. Values are compared by calendar day, ignoring time of day, so events at any time on this day match. Only for datetime and other properties of type date...

_on_or_beforestring<date>

On or before this day, given as YYYY-MM-DD. Values are compared by calendar day, ignoring time of day, so events at any time on this day match. Only for datetime and other properties of type `date...

optionalboolean

Optional stream conditions are unioned together, when combined they define cohorts that meet either stream condition. At least one optional condition must be satisfied.

propertystringrequired

Stream property name.

Maximum characters: 256
stream_namestringrequired

Name of the stream whose events carry the value to forecast.

Example: "stripe_charges"
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 stream property's format (currency_cents or `c...

Example: "amount"
updated_atstring<date-time>required

When this resource was last updated.

400The request was invalid.
errorstringrequired

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...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

401No API key was supplied.
errorstringrequired

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...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

403Access to this resource was forbidden.
errorstringrequired

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...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

404The requested resource ID was not found.
errorstringrequired

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...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

409The request was formatted correctly, but conflicted with an existing resource.
errorstringrequired

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...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

500An internal server error occurred.
errorstringrequired

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...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

Tags

forecasts