Retrieve a forecast

gethttps://api.faraday.ai/v1/forecasts/{forecast_id}
This endpoint is experimental and may change without notice.

Get details on a specific forecast

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

path parameters

forecast_idstring<uuid>required

The UUID of a forecast

Responses

200Information about the 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. With currency_property_name, events in other currencies are converted into it at a reference rate; without, values are summed as recor...

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

Name of the property of stream_name holding each event's ISO 4217 currency code. With currency set as well, an event in another currency is converted into currency at a reference exchange rate (...

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_end_property_namestring

Name of a date or timestamp property on entry_stream_name that records when the entry ended, such as a subscription's ended_at. An entry has ended once that timestamp is at or before the data cuto...

Example: "ended_at"
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
blockedobject

Predictors that modeling must not use.

Additional properties: not allowed
Properties of object
attributesarray[string]

Attributes to block, named as in GET /attributes. Only for accounts that use attributes.

Example: ["fig/age"]
categoriesarray[string enum]

Categories to block. Blocks every trait or attribute in the category.

Example: ["fig/property"]
Allowed values: fig/demography, fig/environment, fig/geography, fig/identity, fig/lifestyle, fig/life_event, fig/property, fig/reachability, fig/society, fig/financial, fig/vehicles, fig/civic, fig/engagement, user_defined
providersarray[string]

The name of a provider whose features should be blocked from consideration.

Options:

  • self: refers to the Account the resource belongs to.
streamsarray[object]

Stream-derived predictors to block, one entry per stream. An entry with only name blocks every
predictor built from the stream. An entry that lists properties or aggregates blocks only those.

Items of array[object]
aggregatesarray[string]

Patterns for the aggregates of this stream to block. Each pattern is a regular expression with no
delimiters, and it must match the whole aggregate name. Patterns block aggregates as a family, since a...

Example: ["COUNT_.*"]
Minimum items: 1
namestringrequired

Name of the stream, as in GET /streams.

Example: "orders"
Maximum characters: 64
propertiesarray[string]

Properties of this stream to block. Blocks every predictor built from each property.

Example: ["total"]
Minimum items: 1
traitsarray[string]

Traits to block, named as in GET /traits. First-party traits use their plain name. On accounts without
attributes, third-party traits use their fig/ name.

Example: ["fav_cookie"]
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 forecast is in the unit the stream property hold...

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.

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