Retrieve the account's Insights

gethttps://api.faraday.ai/v1/insights

One per account, provisioned by your plan. Returns the account's Insights resource: its status, and the tables and columns available to query with POST /insights/query.

Every table and column listed exists and can be queried; they are what the last build produced, less the table of any scope since archived, opted out or set back to preview, which the next build drops. status and last_updated_output_at say whether the tables are built and how fresh they are. A cohort, stream or atlas added since the last build, or a scope whose insights was turned on since then, appears after the next one.

Each scope with insights turned on has its own table, holding the scope's predictions for each person in its population. It covers only that population, so join it to other tables on privacy_unit_column with an inner join. A preview scope's table appears once preview is turned off and the scope's next full build finishes.

To query them:

  • Every query begins SELECT WITH AGGREGATION_THRESHOLD.
  • Tables join on privacy_unit_column.
  • A group backed by fewer than aggregation_threshold distinct people is silently dropped from the results, not reported as an error.
  • Only the functions in allowed_aggregates can be used.
  • The fig table's columns aren't listed beyond its fixed ones. It also has one column per attribute on the account's feature store (identity_graph.feature_store_id on GET /accounts/current), named by the attribute's name; GET /attributes describes them.

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

Responses

200The account's Insights.
aggregation_thresholdintegerrequired

The fewest distinct people that can stand behind any returned row. Smaller groups are dropped from results.

Example: 50
allowed_aggregatesarray[string]required

The aggregate functions queries can use.

Example: ["COUNT","COUNTIF","SUM","AVG"]
created_atstring<date-time>required

When this resource was created.

idstring<uuid>required

A unique ID for this resource.

Example: "4f0c6a55-2d8e-4b1a-9a3e-0f7e5b2c9d11"
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.

privacy_unit_columnstringrequired

The column that identifies a person in every table. Tables join on it, and the aggregation threshold counts distinct values of it.

Example: "person_key"
resource_typestringrequired

The type of this resource.

Example: "insights"
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.

tablesarray[object]required

The tables available to query. Empty until the first build.

Items of array[object]
bigquery_tablestringrequired

The table's fully qualified BigQuery name, which is what a query names in its FROM clause.

Example: "production-237317.insights_persons.account_062215f0_10e8_446e_bdec_22c5c98a1af0_persons"
columnsarray[object]required

The table's columns. For fig, only its fixed columns; it also has one column per attribute on the account's feature store, named by the attribute's name, which GET /attributes describes.

Items of array[object]
namestringrequired
Example: "is_customers"
sourceobject

The cohort, stream, atlas, persona set, outcome, forecast or recommender a column comes from. Omitted for a column with no single source, such as the privacy unit.

Additional properties: not allowed
Properties of object
resource_idstring<uuid>required

The ID of the cohort, stream, atlas, persona set, outcome, forecast or recommender.

resource_typestringrequired

The type of a resource which is available via the REST SDK.

Example: "scopes"
Allowed values: accounts, atlases, attributes, cohorts, connections, datasets, feature_stores, forecasts, insights, market_opportunity_analyses, migrations, outcomes, persona_sets, places, recommenders, scopes, streams, targets, traits
typestringrequired

The column's BigQuery type, such as INT64, BOOL or STRING. These are BigQuery's own type names, since queries are written in BigQuery SQL.

Example: "BOOL"
namestringrequired

The table's short name, such as persons, fig, events, events_rollup, <slug>_catchment, or scope_<scope id> (the scope's id without hyphens).

Example: "persons"
sourceobject

The resource whose output a table holds, such as the scope behind a scope table or the atlas behind a catchment table. Omitted for a table that is not one resource's output, such as persons, fig or events.

Additional properties: not allowed
Properties of object
resource_idstring<uuid>required

The ID of the scope or atlas.

resource_typestringrequired

The type of resource whose output an Insights table holds. New values may be added as new kinds of Insights table appear.

Example: "scopes"
Allowed values: atlases, scopes
updated_atstring<date-time>required

When this resource was last updated.

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

insights