Query your users activity over the last seven days.
If you regularly use the moderation platform, or the audio tagging API, you can use this endpoint to fetch recent results.
Concepts
Starting a Query - Queries are asynchronous. When you request a query, you are given a job identifier to exchange for a future completed query.
Data Availability - Data is available up to seven days from the day in which it is committed by an applicable endpoint request. It is currently not possible to query beyond those seven days for compliance reasons (we erase timestamps and attempt to clean PII, to prevent comments being personally identifiable on timestamps across our users).
Data structure - Data is sorted by requestTime
, in a descending manner (most recent to least recent).
Job Expiry - Completed jobs (whether successful or not), are kept for 24 hours.
Request - Start a Query
POST https://api.chatsight.ai/insights/community/query
HEADER x-chatsight-api-auth: <API-TOKEN>
curl --location --request POST 'https://api.chatsight.ai/insights/community/query' \
--header 'x-chatsight-api-auth: <YOUR_API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{"timefrom":"2021-05-01 00:27:00","timeto":"2021-05-04 21:30:00","maxresults":1000,"metric":"sentiment"}'
Key | Value | Description |
---|---|---|
timefrom | STRING | Time to search from. A UTC formatted datetime string. YYYY-MM-DD HH:MM:SS |
timeto | STRING | Time to search until and up to. A UTC formatted datetime string. YYYY-MM-DD HH:MM:SS |
maxresults | NUMBER | The maximum results to return. A hard-maximum of 5000 is enforced. |
metric | STRING | Choose the metric to query. Available metrics: - sentiment - language_political - language_vulgarity |
Response
{
"api": "chatsight-lang-text",
"success": true,
"response": {
"status": "Provisioning",
"jobid": "f1gRozC1w5iHP6Kid2zhET", // Take note of this, as you will need it to view the completed job.
"metric": "sentiment"
}
}
Request - Check Query Status
Check the status of a query. When the query is finished, the status
property will either be Finished
or Failed
. A parameter view
needs to be set to status
to check on the job status.
GET https://api.chatsight.ai/insights/community/query/<jobid>?view=<viewType>
HEADER x-chatsight-api-auth: <API-TOKEN>
curl --location --request GET 'https://api.chatsight.ai/insights/community/query/f1gRozC1w5iHP6Kid2zhET?view=status' \
--header 'x-chatsight-api-auth: <YOUR_API_TOKEN>' \
Key | Value | Description |
---|---|---|
jobid | STRING | The Job ID obtained from starting a query request. |
viewType | STRING | A query parameter, with a value of either status or results . In this case, we want to check what the status of the Query Job is. |
Response
{
"api": "chatsight-lang-text",
"success": true,
"response": {
"jobid": "f1gRozC1w5iHP6Kid2zhET",
"metric": "sentiment",
"status": "In Progress"
}
}
{
"api": "chatsight-lang-text",
"success": true,
"response": {
"jobid": "f1gRozC1w5iHP6Kid2zhET",
"metric": "sentiment",
"status": "Finished"
}
}
{
"api": "chatsight-lang-text",
"success": true,
"response": {
"jobid": "f1gRozC1w5iHP6Kid2zhET",
"metric": "sentiment",
"status": "Failed"
}
}
Request - Get the results of the Query
Once a query returns a status of Finished
, you can fetch the results in a way similar to checking the query status. This time, set the view
query string's value to results
.
GET https://api.chatsight.ai/insights/community/query/<jobid>?view=<viewType>
HEADER x-chatsight-api-auth: <API-TOKEN>
curl --location --request GET 'https://api.chatsight.ai/insights/community/query/f1gRozC1w5iHP6Kid2zhET?view=results' \
--header 'x-chatsight-api-auth: <YOUR_AUTH_TOKEN>' \
Response
Our response details your requested metric to query, along with a copy of the sample.
requestTime
is formatted in the ISO 8601
standard for displaying time.
{
"api": "chatsight-lang-text",
"success": true,
"response": [
{
"SAMPLE": "I really love going to get pizza at the pier.",
"SENTIMENT": 0.5,
"requestTime": "2021-05-11T04:42:21.000Z",
"VERSION": "2.0"
},
{
"SAMPLE": "Damn that really makes me upset that, that pizza place closed.",
"SENTIMENT": -0.3,
"requestTime": "2021-05-11T04:42:16.000Z",
"VERSION": "2.0"
},
{
"SAMPLE": "I'm really happy, but really sad at the same time.",
"SENTIMENT": 0,
"requestTime": "2021-05-11T04:40:56.000Z",
"VERSION": "2.0"
}
]
}