Community Querying

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"
        }
    ]
}