Skip to main content
POST
/
v016
Detailed survey response analysis
curl --request POST \
  --url https://api.roundtable.ai/alias/v016 \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api_key>' \
  --data '
{
  "participant_id": "participant_123",
  "questions": {
    "Q1": "How do you feel our software has impacted your daily workflow?"
  },
  "responses": {
    "Q1": "I really like pineapple on pizza."
  },
  "survey_id": "survey_456",
  "question_histories": {
    "Q1": [
      {
        "s": "I",
        "t": 0
      },
      {
        "s": "Im",
        "t": 429
      }
    ]
  },
  "low_effort_threshold": 0
}
'
{
  "error": false,
  "flagged": true,
  "num_checks_failed": 1,
  "response_groups": {
    "Q1": 1
  },
  "checks": {
    "Q1": [
      "Automated test: Off-topic"
    ]
  },
  "effort_ratings": {
    "Q1": 4
  },
  "model": "alias-v016"
}

Headers

​
api_key
string
required

API key for authentication. Include this in the header of your request.

Body

application/json
​
participant_id
string
required

A unique identifier for the participant.

Example:

"participant_123"

​
questions
object
required

Contains the survey questions. Each key is the id of the question, and the values are the text of the open-ended survey questions as shown to the participant.

Example:
{
  "Q1": "How do you feel our software has impacted your daily workflow?"
}
​
responses
object
required

Records the participant's final responses to each question.

Example:
{ "Q1": "I really like pineapple on pizza." }
​
survey_id
string
required

A unique identifier for the survey.

Example:

"survey_456"

​
question_histories
object

Records the changes made by the participant while answering the survey. Each key is the id of the question, and the value is the array of changes generated by our Javascript tracker. See here for more instructions.

Example:
{
  "Q1": [
    { "s": "I", "t": 0 },
    { "s": "Im", "t": 429 }
  ]
}
​
low_effort_threshold
integer
default:0

Threshold for flagging a response as low effort. Must be between 0 and 10.

Required range: 0 <= x <= 10

Response

200 - application/json

Analysis result

​
error
boolean

Indicates if there was an error in processing the request.

Example:

false

​
flagged
boolean

Indicates if any fraudulent or inappropriate activity was detected.

Example:

true

​
num_checks_failed
integer

Number of checks that failed.

Example:

1

​
response_groups
object

Dictionary where key corresponds to question_id and value corresponds to the cluster of duplicated responses.

Example:
{ "Q1": 1 }
​
checks
object

Dictionary where keys correspond to questions, and every entry is an array of strings, each string representing a failed check. Possible checks include:

  • "Automated test: Gibberish" - The response is not coherent or grammatical.
  • "Automated test: Off-topic" - The response does not address or relate to the question.
  • "Automated test: GPT" - The response is flagged as likely generated by a GPT model.
  • "Automated test: Profane" - The response contains profane or inappropriate language.
  • "Low-effort" - The response relates to the question but provides minimal information. This is flagged if the effort score is less than or equal to the low_effort_threshold.
  • "GPT paste artifacts" - The text is formatted similarly to ChatGPT outputs.
  • "Programmatic entry" - The response was entered programmatically.
  • "Response pasted" - The response was pasted or entered all at once.
  • "Self-duplicate response" - A similar or identical answer was given to more than one question.
  • "Cross-duplicate response" - A similar or identical answer as another participant was provided.
  • "Unnatural typing" - Typing behavior flagged as likely non-human.
Example:
{ "Q1": ["Automated test: Off-topic"] }
​
effort_ratings
object

Dictionary where key corresponds to question_id and value is an effort score from 1-10, with 1 being minimal effort and 10 being high effort.

Example:
{ "Q1": 4 }
​
model
string

String specifying the model type.

Example:

"alias-v016"