Taskflow

Taskflow is designed to facilitate the creation and management of single studies with varied configurations. By utilizing Taskflow, you can seamlessly implement A/B testing with different external URLs and distribution strategies, ensuring comprehensive data collection and analysis from your participants.

• Key Features:
  • Flexible Study Creation: Easily set up studies with multiple variations in external URLs, enabling targeted testing and comparison.
  • A/B Testing: Conduct robust A/B testing to evaluate different versions of your study, allowing for precise measurement of participant responses and behaviors.
  • Granular Distribution: Fine grained control over the distribution of your URLs to a subsection of participants.
  • Task Assignment Efficiency: Ideal for scenarios where you need to assign small numbers of participants to specific unique tasks. This streamlines the management process by handling a single study rather than managing multiple small studies.

Below is an example of how Taskflow reduces the study management complexity:

To get started with Taskflow, see the Create Study Documentation

Screenouts and Allocation Capacity

If your Taskflow study uses custom screening with a fixed screen-out reward, participants who are screened out affect the allocation counts on your URLs. Understanding how this works helps you interpret the progress data and avoid unexpected capacity shortfalls.

How screenouts interact with URL capacity

When you create a Taskflow study you set a total_allocation for each URL — this is the base number of participants you want allocated to that URL, and it determines the study’s total_available_places.

When a participant is screened out, they have consumed a screening interaction but have not completed the study. Taskflow automatically restores one available slot for that URL so that a replacement participant can be allocated in their place. It does this by tracking the cumulative number of screenouts separately in a capacity_increments field, rather than modifying your total_allocation base value.

This means:

• total_allocation always reflects the base value you set — it is the figure used to determine the study’s total available places.
• capacity_increments records how many extra slots have been added by screenouts.
• allocated tracks the total number of participants currently assigned to the URL. For studies with screenouts this can legitimately exceed total_allocation. The relationship is always: allocated ≤ total_allocation + capacity_increments.

Reading the progress endpoint

The GET /api/v1/studies/{id}/access-details-progress/ endpoint returns these fields per URL:

Example: A URL with total_allocation: 10 has had 3 participants screened out. The progress response will show:

1
{
2
  "external_url": "https://example.com/survey",
3
  "total_allocation": 10,
4
  "allocated": 11,
5
  "capacity_increments": 3
6
}

This means 11 participants have been allocated, 3 of whom were replacements for screened-out participants. The effective ceiling is 13 (10 + 3), so 2 slots remain.

Increasing capacity after screenouts

If your study is running low on available slots due to screenouts, you can increase capacity by updating your study’s access_details via PATCH /api/v1/studies/{id}/. The total_allocation value you submit becomes the new base — your accumulated capacity_increments are preserved automatically on top of it.

For example, if your current state is total_allocation: 10, capacity_increments: 3 and you submit a PATCH with total_allocation: 20, the effective ceiling becomes 23 (20 + 3).