---
title: "Lock Tasks Endpoint"
method: POST
path: "/api/tasks/lock"
tags: ["tasks"]
---

# Lock Tasks Endpoint

`POST /api/tasks/lock`

## Request

- Base URL: `https://api.mit-llm-survey.academy` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mit-llm-survey.academy/api/tasks/lock`
- Auth: none declared

Lock available tasks for a specific occupation and prolific_id.

**Parameters:**
- **occupation_id**: The occupation ID to filter tasks
- **prolific_id**: The prolific ID to assign tasks to
- **limit**: Maximum number of task groups to return (default: 6). Each group contains 1-3 task instances.
             For example, limit=6 returns 6 groups with a total of 6-18 tasks.
- **preview**: Preview mode flag (default: True)
    - **True**: Returns available tasks without locking them. No database changes are made.
    - **False**: Actually locks the tasks in the database and assigns them to the prolific_id.

**Task Grouping Logic:**
- Tasks are formatted as xxx-1, xxx-2, xxx-3, xxx-4, xxx-5, xxx-6
- Tasks are grouped by prefix (xxx)
- **Only available tasks are fetched.** Completed groups (groups with >= 2 unavailable task instances) are excluded at the database level and are never returned.
- For each prefix returned, up to 3 newest task instances are selected (created_at desc)
- Groups are returned in newest-first order (max created_at in the group)
- Each group will have at least 1 task instance and at most 3 task instances
- If a prefix has more than 3 available tasks, the 3 newest are selected
- If a prefix has 1-3 available tasks, all are included
- Up to 'limit' groups are returned (e.g., limit=6 returns 6 groups)
- Total tasks returned will be between 6 (6 groups × 1 task min) and 18 (6 groups × 3 tasks max)

**Example:**
- Prefix 1: has 3 available tasks (e.g. 1-1, 1-2, 1-4) → group is included with those 3 tasks
- Prefix 2: is completed (>= 2 unavailable) → group is not fetched at all; only groups with < 2 unavailable are returned

**Returns:**
TaskGroupResponse containing grouped tasks with metadata (total_groups, total_tasks).

## Request body

- LockTasksRequest
  - `occupation_id` string, required
  - `prolific_id` string, required
  - `limit` integer
  - `preview` boolean

## Response `200`

Successful Response

- TaskGroupResponse
  - `groups` TaskGroup[], required
    - `group_id` string, required
    - `task_desc` string, required
    - `items` TaskRead[], required
      - `occupation_id` string, required
      - `task_url` string, required
      - `task_desc` string, required
      - `response_url_1` string, nullable
      - `response_url_2` string, nullable
      - `response_url_3` string, nullable
      - `response_url_4` string, nullable
      - `response_url_5` string, nullable
      - `available` string
      - `prolific_id` string, nullable
      - `qualtrics_id` string, nullable
      - `history` string, nullable
      - `locked_history` string, nullable
      - `is_deleted` string, date-time, nullable
      - `models_order` string, nullable
      - `task_id` string, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
  - `total_groups` integer, required
  - `total_tasks` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mit-llm-survey/apis/llm-survey-backend.md) - [All operations](https://skmtc.dev/mit-llm-survey/apis/llm-survey-backend/llms.txt) - [OpenAPI document](https://skmtc.dev/mit-llm-survey/apis/llm-survey-backend/revisions/6a5ef49cfcc4?raw)