Human surveys

humanize() turns an EDSL Survey into a web questionnaire that people can complete. It preserves the questions and survey logic while adding a respondent interface, an administration page, and response collection. Start with Human studies for a short end-to-end example; use this page to configure scenarios, respondent lists, and data retrieval.

This page covers code methods for launching surveys, gathering human responses, and analyzing results. For interactive survey building, see Survey Builder. For Prolific recruitment, see Prolific studies. For email notifications and scheduled reminders, see Survey notifications. To let AI agents take a survey, see AI agent access.

How it works

Create Surveys with desired types of Questions.

Humanize the survey to generate a web-hosted version on Expected Parrot with a respondent link and an admin dashboard.

Share the respondent link with human participants (or recruit via Prolific).

Collect responses back as a standard EDSL Results object.

Analyze your human results alongside any LLM results.

Basic usage

The example collects three measures of workplace experience: work-from-home frequency, satisfaction, and a suggested improvement. After defining the questions, .humanize() publishes them using your Expected Parrot account.

from edsl import Survey, QuestionMultipleChoice, QuestionFreeText, QuestionLinearScale

q1 = QuestionMultipleChoice(
    question_name="frequency",
    question_text="How often do you work from home?",
    question_options=["Never", "1-2 days a week", "3-4 days a week", "Every day"],
)
q2 = QuestionLinearScale(
    question_name="satisfaction",
    question_text="How satisfied are you with your current work arrangement?",
    question_options=[1, 2, 3, 4, 5],
    option_labels={1: "Very dissatisfied", 5: "Very satisfied"},
)
q3 = QuestionFreeText(
    question_name="improvement",
    question_text="What one change would most improve your day-to-day work experience?",
)

survey = Survey([q1, q2, q3])

info = survey.humanize(
    human_survey_name="Workplace Experience Survey",
    survey_description="A short survey about remote and in-office work preferences.",
    survey_visibility="unlisted",
)

info  # Contains the respondent link, admin link, and collection UUID.

`.humanize()` parameters

Parameter	Type	Default	Description
`human_survey_name`	str	`"New survey"`	Display name on Expected Parrot
`survey_description`	str \| None	None	Optional description
`survey_alias`	str \| None	None	URL-friendly alias
`survey_visibility`	str	`"private"`	`"private"`, `"public"`, or `"unlisted"`
`humanize_schema`	dict \| None	None	Controls question settings and survey options, including requiring Expected Parrot sign-in — see Humanize schema

Return value

survey.humanize() returns a Scenario (dict-like) with these keys:

Key	Description
`uuid`	Human survey UUID — needed to fetch responses later
`respondent_url`	Public link for respondents
`admin_url`	Admin dashboard link
`name`	Survey name
`n_complete`	Completed responses (0 at creation)
`n_in_progress`	Responses started but not yet finished (0 at creation)
`survey_uuid`	UUID of the pushed survey object
`scenario_list_uuid`	UUID of the pushed scenario list (if any)
`asset_substitutions`	Old asset uuid → new one, when the schema named assets that were copied into your library. Empty when nothing was copied

Save the uuid — you need it to retrieve responses.

Previewing before deployment

Use .preview() to get a preview URL without creating a live survey:

preview_url = survey.preview()
# print() also shows output in scripts. In a notebook, you can instead
# put the value you want to inspect on the last line of a cell.
print(preview_url)

# With schema customization
schema = {"questions": {"improvement": {"optional": True}}}
preview_url = survey.preview(humanize_schema=schema)

Present questions in groups

To request one group per page, define contiguous question groups on the survey and pass humanize_schema={"survey": {"presentation": "group"}} to .humanize(). See Grouped surveys for a complete example, branching behavior, and availability requirements.

Add your logo

To show your own logo above the questions, upload the image once and reference it from the humanize schema:

from edsl import Coop

logo = Coop().upload_human_survey_asset("lab_logo.png")

survey.humanize(
    human_survey_name="Customer feedback",
    humanize_schema={
        "survey": {
            "branding": {
                "logo": {
                    "source": {"type": "asset", "asset_uuid": logo.uuid},
                    "alt": "Acme Research logo",
                }
            }
        }
    },
)

Uploading the same file again returns the asset you already have, so re-running a script does not fill your library with copies. Coop().list_human_survey_assets(page=1, page_size=20) lists a page of image-library metadata. Coop().get_human_survey_asset(asset_uuid) returns a HumanSurveyAsset; its download("logo.png") method saves the image locally. Coop().delete_human_survey_asset(asset_uuid) removes an asset when you intend to delete it. From the CLI, upload once and apply it to a survey that already exists:

ep humanize assets upload lab_logo.png
ep humanize schema set <human-survey-uuid> --logo-asset <asset-uuid> --logo-alt "Acme Research logo"

Or do both in one step:

ep humanize schema set <human-survey-uuid> --logo-file lab_logo.png --logo-alt "Acme Research logo"

See Humanize schema for the branding fields, and Custom CSS for resizing the logo or putting it on a colored banner.

With scenarios

When using scenarios, call .humanize() on a Jobs object (not directly on the survey). You must specify a scenario_list_method. Use scenarios for stimulus material or treatment conditions. This example assigns each respondent one of three policy descriptions and asks for a support rating and its reason. Random assignment can select the same policy for several respondents:

from edsl import Survey, QuestionFreeText, QuestionLinearScale, Scenario, ScenarioList

scenarios = ScenarioList([
    Scenario({"policy": "Four-day workweek with no change in pay"}),
    Scenario({"policy": "Flexible start times between 7am and 11am"}),
    Scenario({"policy": "Monthly remote-work stipend of $100"}),
])

q1 = QuestionLinearScale(
    question_name="support",
    question_text="How much do you support this policy: '{{ scenario.policy }}'?",
    question_options=[1, 2, 3, 4, 5],
    option_labels={1: "Strongly oppose", 5: "Strongly support"},
)
q2 = QuestionFreeText(
    question_name="reasoning",
    question_text="What is the main reason for your rating?",
)

survey = Survey([q1, q2])

info = survey.by(scenarios).humanize(
    human_survey_name="Workplace Policy Reactions",
    scenario_list_method="randomize",
)

Set question options from an earlier answer

Use a Jinja template for question_options when a later question’s choices depend on an earlier answer. Put the lookup data in a scenario; the survey server resolves the template after the respondent answers the first question and sends only the matching options to that page. A QuestionDropdown answer is a list, so [0] selects its single choice. This example downloads O*NET’s Task Statements CSV, builds a task list for each occupation, then shows the selected occupation’s tasks in a checkbox question:

import csv
from collections import defaultdict
from io import TextIOWrapper
from urllib.request import urlopen

from edsl import (
    QuestionCheckBox,
    QuestionDropdown,
    Scenario,
    ScenarioList,
    Survey,
)

task_url = "https://www.onetcenter.org/dl_files/database/db_31_0_csv/task_statements.csv"
tasks_by_occupation = defaultdict(list)

with urlopen(task_url) as response:
    rows = csv.DictReader(TextIOWrapper(response, encoding="utf-8-sig"))
    for row in rows:
        choice = f"{row['Title']} [{row['O*NET-SOC Code']}]"
        tasks_by_occupation[choice].append(row["Task"])

occupation = QuestionDropdown(
    question_name="occupation",
    question_text="Which O*NET occupation best describes your work?",
    question_options=list(tasks_by_occupation),
    top_k=1,
)
tasks = QuestionCheckBox(
    question_name="tasks",
    question_text="Which tasks are part of your work?",
    question_options="{{ scenario.tasks_by_occupation[occupation.answer[0]] }}",
)

survey = Survey([occupation, tasks])
scenario = Scenario({"tasks_by_occupation": dict(tasks_by_occupation)})
info = survey.by(ScenarioList([scenario])).humanize(
    human_survey_name="Occupation and Tasks",
    scenario_list_method="single_scenario",
)

print(info["respondent_url"])

O*NET 31.0 includes 18,838 task statements across 923 occupations. This example includes occupations present in the task file; taxonomy occupations without task statements are left out. For respondent-facing options, the scenario-backed Jinja lookup is the direct approach. The QuestionCompute variant below embeds the lookup in the survey when you need a self-contained definition.

Embed the lookup in a `QuestionCompute`

For a self-contained survey, you can put the lookup dictionary directly in a QuestionCompute template instead of attaching it as a scenario. The compute question reads the prior dropdown answer, and the checkbox receives its answer as its options:

import json

from edsl import QuestionCompute

# Reuse `tasks_by_occupation` and `occupation` from the example above.
lookup_json = json.dumps(
    dict(tasks_by_occupation), ensure_ascii=False, separators=(",", ":")
)

available_tasks = QuestionCompute(
    question_name="available_tasks",
    question_text="{{ " + lookup_json + "[occupation.answer[0]] }}",
)
tasks = QuestionCheckBox(
    question_name="tasks",
    question_text="Which tasks are part of your work?",
    question_options="{{ available_tasks.answer }}",
)

survey = Survey([occupation, available_tasks, tasks])
info = survey.humanize(human_survey_name="Occupation and Tasks")
print(info["respondent_url"])

The QuestionCompute is an intermediate question; respondents see the occupation dropdown and task checkbox. This avoids a scenario attachment, but serializes the full lookup into the question text. For O*NET 31.0 that is about 1.9 MB, which worked in a local live survey. The scenario-backed version above keeps the question definition much smaller and is easier to maintain; embedding can be reasonable when a self-contained survey is more useful.

Scenario list methods

Method	Behavior
`"randomize"`	Each respondent gets a random scenario (with replacement)
`"ordered"`	Scenarios are assigned sequentially to respondents
`"loop"`	Survey is expanded — every question is repeated for every scenario
`"single_scenario"`	Exactly one scenario is used for all respondents (list must have length 1)

Rules:

If you attach scenarios, you must specify scenario_list_method.
If you specify a method, you must attach scenarios.
Do not attach language models to a human-survey job. An AgentList can supply participant metadata and delivery addresses, as described below; it does not generate simulated responses.

With agent lists (for email notifications)

Attach an AgentList via .by() to associate respondents with email addresses. Pass a DeliveryMap to tell Coop which agent trait holds the email address.

from edsl import Survey, Agent, AgentList
from edsl.coop.coop_humanize_notifications import ChannelConfig, DeliveryMap

agents = AgentList([
    Agent(traits={"name": "Jordan", "email": "[email protected]"}),
    Agent(traits={"name": "Taylor", "email": "[email protected]"}),
    Agent(traits={"name": "Morgan", "email": "[email protected]"}),
])

info = survey.by(agents).humanize(
    human_survey_name="Panel Study — Wave 1",
    agent_list_description="Recruited panel participants",
    delivery_map=DeliveryMap(email=ChannelConfig(col_name="email")),
)

col_name must match the trait key that holds each respondent’s email address. Once deployed, use Survey notifications to send invitations, schedule reminders, and track delivery status.

Retrieving responses

from edsl import Coop

coop = Coop()

results = coop.get_human_survey_responses("your-human-survey-uuid")
# In a notebook, the last expression displays the selected table.
# In a script, append .print() to display it.
results.select("answer.frequency", "answer.satisfaction", "answer.improvement")

What the results contain

Each completed response is one result, oldest first. Retrieving data reads the recorded answers; it does not rerun the questionnaire. Skipped questions stay skipped. Column names match the responses table on the survey’s page. Select scenario.* alongside answers when you need to compare the material or condition each respondent received.

Field	Description
`answer.{question}`, `comment.{question}_comment`	The respondent’s answer and comment. Empty for a question they didn’t see.
`agent.response_uuid`, `agent.agent_name`	The response’s ID.
`agent.response_status`	`complete`, or `in_progress` for a response still being taken (see below).
`agent.last_activity_at`	When the respondent last moved the response forward.
`agent.respondent_uuid`, `agent.agent_index`	The respondent’s ID and position in the attached agent list. Empty without an agent list.
`agent.{trait}`	The traits of the respondent’s agent, when an agent list is attached.
`agent.expectedparrot_username`	The respondent’s Expected Parrot username, when the survey requires account sign-in.
`raw_model_response.{question}_started_at`, `_answered_at`	When the respondent reached and answered the question.
`raw_model_response.{question}_question_presented`	`False` if survey logic skipped the question, so a skipped question can be told from one left blank.
`question_options.{question}_question_options`	The options as the respondent saw them, after piping and any randomized order.
`agent.external_platform`, `agent.prolific_*`	The Prolific submission, study and participant IDs, when any response came through Prolific.

Fields that show how a response was collected, such as agent.collection_interface, are listed under AI agent access. The model.* columns describe a placeholder model: a human response has no model, but every result records one. To get only some responses, pass started_after and/or started_before (inclusive; a response is “started” when the respondent opened the survey).

In-progress responses

By default you get completed responses only. Pass include_partial=True to also get responses that are still being taken, for example to look at dropout or check on a survey that is still running:

results = coop.get_human_survey_responses(
    "your-human-survey-uuid", include_partial=True
)
results.filter("agent.response_status == 'in_progress'").select(
    "agent.response_uuid", "agent.last_activity_at"
)

An in-progress response holds the answers submitted so far; questions the respondent hasn’t answered yet are empty. Filter to agent.response_status == 'complete' before computing anything that assumes a finished survey. A response that is in progress now can have more answers, or be complete, the next time you fetch, so combine downloads by agent.response_uuid. include_partial works together with started_after and started_before.

Checking response count

status = coop.get_human_survey("your-human-survey-uuid")
print(f"Completed: {status['n_complete']}, in progress: {status['n_in_progress']}")

Find surveys and inspect respondent progress

Use Python pagination when retrieving account records:

surveys = coop.list_human_surveys(search_query="Workplace", page=1, page_size=20)
respondents = coop.get_human_survey_respondents(
    "your-human-survey-uuid", page=1, page_size=50,
)
respondents

These calls return response dictionaries with records and pagination information; inspect the returned metadata before requesting another page. coop.get_human_survey_agent_list(uuid) retrieves the attached respondent list configuration. To change its delivery mapping or participation settings, use coop.patch_human_survey_agent_list(...); see notifications and AI agent access. For events logged by a survey’s custom JavaScript, coop.get_human_survey_events(uuid, limit=200) retrieves a batch. While has_more is true, pass the returned next_cursor as after to continue, or use coop.get_all_human_survey_events(uuid) to collect all batches. coop.count_human_survey_events(uuid) counts those events. Preview events are included and marked is_preview; exclude them from participant analyses. Use get_human_survey_responses() for answer data.

Working with file upload responses

If your survey includes a QuestionFileUpload question, each response’s answer for that question is a list of file-info dicts. Use FileStore.from_file_upload_answer (single file) or FileStoreList.from_file_upload_answers (all files at once) to download and wrap them:

from edsl import Coop
from edsl.scenarios import FileStore, FileStoreList

coop = Coop()

results = coop.get_human_survey_responses("your-human-survey-uuid")

# Each answer is a list of uploaded file dicts
uploaded_files = results[0]["answer"]["my_upload_question"]

# Download all files as a FileStoreList
fsl = FileStoreList.from_file_upload_answers(uploaded_files)

# Or download a single file
fs = FileStore.from_file_upload_answer(uploaded_files[0])

The returned FileStore and FileStoreList objects behave like any other — you can inspect, filter, or pass them into further EDSL workflows.

QR code

Generate a QR code for the respondent link using get_human_survey_qr_code(). Requires the qrcode library (pip install "edsl[full]" or pip install "qrcode[pil]").

from edsl import Coop

coop = Coop()

qr = coop.get_human_survey_qr_code("your-human-survey-uuid")
qr.save("qr_code.png")  # save to file

From the CLI, generate a QR code for the shared respondent URL:

ep humanize qr <human-survey-uuid> --output survey-qr.png

When the human survey has an attached agent list, export the roster together with each respondent’s personal link:

links = coop.get_human_survey_respondent_links(
    "your-human-survey-uuid", save_path="respondent-links.csv",
)
# links is a Dataset; the CSV contains the personal respondent URLs.

The CLI alternative is:

ep humanize links <human-survey-uuid> --output respondent-links.csv

Add --qr-dir to generate one personal QR code per respondent and record each PNG path in the CSV:

ep humanize links <human-survey-uuid> \
  --output respondent-links.csv \
  --qr-dir respondent-qr

Personal links and QR codes contain access tokens and act as bearer credentials. Store the export securely and share each link or code only with its intended respondent. The CLI returns only file metadata on stdout, never the links.

Prolific integration

For paid recruitment, see Prolific recruitment. That guide covers account limits, cost estimation, draft creation, preflight checks, publication, and response retrieval.

Introduction

Setup and tutorials

EDSL objects

How-to guides

Research examples

Human research

Execution and costs

Saving and sharing

Research and teaching

Expected Parrot platform

Contributing

How it works

Basic usage

`.humanize()` parameters

Return value

Previewing before deployment

Present questions in groups

Add your logo

With scenarios

Set question options from an earlier answer

Embed the lookup in a `QuestionCompute`

Scenario list methods

With agent lists (for email notifications)

Retrieving responses

What the results contain

In-progress responses

Checking response count

Find surveys and inspect respondent progress

Working with file upload responses

QR code

Prolific integration

​How it works

​Basic usage

​.humanize() parameters

​Return value

​Previewing before deployment

​Present questions in groups

​Add your logo

​With scenarios

​Set question options from an earlier answer

​Embed the lookup in a QuestionCompute

​Scenario list methods

​With agent lists (for email notifications)

​Retrieving responses

​What the results contain

​In-progress responses

​Checking response count

​Find surveys and inspect respondent progress

​Working with file upload responses

​QR code

​Prolific integration

How it works

Basic usage

`.humanize()` parameters

Return value

Previewing before deployment

Present questions in groups

Add your logo

With scenarios

Set question options from an earlier answer

Embed the lookup in a `QuestionCompute`

Scenario list methods

With agent lists (for email notifications)

Retrieving responses

What the results contain

In-progress responses

Checking response count

Find surveys and inspect respondent progress

Working with file upload responses

QR code

Prolific integration