Run an Insights query
https://api.faraday.ai/v1/insights/queryRuns one aggregate GoogleSQL query against the tables GET /insights lists and returns the result rows. Synchronous: the rows come back in the response, and nothing is stored.
The query must be a single SELECT WITH AGGREGATION_THRESHOLD statement naming only those tables, fully qualified. Rows backed by fewer than the aggregation threshold of distinct people are omitted, so a missing group means "too few people", not "none".
A query is refused with a message saying why: 400 if it breaks the query rules, reaches a table it may not, would single out individuals or would scan more than the per-query limit; 429 once the account has used its daily query or slot-hour allowance (Retry-After gives the seconds until it resets at 00:00 UTC); and 403 once the account has had too many queries refused on privacy or security grounds in the last 30 days. The daily allowances and the refusal limit appear in GET /usages.
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
One GoogleSQL SELECT statement beginning with SELECT WITH AGGREGATION_THRESHOLD (a leading WITH clause is allowed), naming only tables GET /insights lists, fully qualified in backticks.
"SELECT WITH AGGREGATION_THRESHOLD p.state, COUNTIF(p.is_customers) AS customers, COUNT(*) AS people FROM `production-237317.insights_persons.account_062215f0_10e8_446e_bdec_22c5c98a1af0_persons` p GROUP BY p.state"1Responses
200The query's result rows.
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, 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.
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.
429The account has used its allowance for this period.
Response headers
Retry-AfterintegerSeconds until the allowance resets.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 POST 'https://api.faraday.ai/v1/insights/query' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"sql": "SELECT WITH AGGREGATION_THRESHOLD p.state, COUNTIF(p.is_customers) AS customers, COUNT(*) AS people FROM `production-237317.insights_persons.account_062215f0_10e8_446e_bdec_22c5c98a1af0_persons` p GROUP BY p.state"
}'Example response
{
"row_count": 2,
"rows": [
{}
],
"truncated": false
}