Retrieve the account's Insights
https://api.faraday.ai/v1/insightsOne 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 exactly what the last build produced. 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 appears after the next one.
To query them:
- Every query begins
SELECT WITH AGGREGATION_THRESHOLD. - Tables join on
privacy_unit_column. - A group backed by fewer than
aggregation_thresholddistinct people is silently dropped from the results, not reported as an error. - Only the functions in
allowed_aggregatescan be used. - The
figtable'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_idonGET /accounts/current), named by the attribute'sname;GET /attributesdescribes them.
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_TOKENResponses
200The account's Insights.
The fewest distinct people that can stand behind any returned row. Smaller groups are dropped from results.
50The aggregate functions queries can use.
["COUNT","COUNTIF","SUM","AVG"]When this resource was created.
A unique ID for this resource.
"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.
The column that identifies a person in every table. Tables join on it, and the aggregation threshold counts distinct values of it.
"person_key"The 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.
The tables available to query. Empty until the first build.
When this resource was last updated.
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, CONFLICT, QUOTA_EXCEEDEDA 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, CONFLICT, QUOTA_EXCEEDEDA 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, CONFLICT, QUOTA_EXCEEDEDA 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, CONFLICT, QUOTA_EXCEEDEDA 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 GET 'https://api.faraday.ai/v1/insights' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY'Example response
{
"aggregation_threshold": 50,
"allowed_aggregates": [
"COUNT",
"COUNTIF",
"SUM",
"AVG"
],
"created_at": "2024-01-01T12:00:00Z",
"id": "4f0c6a55-2d8e-4b1a-9a3e-0f7e5b2c9d11",
"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",
"privacy_unit_column": "person_key",
"resource_type": "insights",
"status": "pending",
"status_changed_at": "2024-01-01T12:00:00Z",
"status_error": "string",
"tables": [
{
"bigquery_table": "production-237317.insights_persons.account_062215f0_10e8_446e_bdec_22c5c98a1af0_persons",
"columns": [
{
"name": "is_customers",
"source": {
"resource_id": "123e4567-e89b-12d3-a456-426614174000",
"resource_type": "scopes"
},
"type": "BOOL"
}
],
"name": "persons"
}
],
"updated_at": "2024-01-01T12:00:00Z"
}