---
title: "Create task event"
method: POST
path: "/api/tasks/{id}/events/"
tags: ["Task Events"]
---

# Create task event

`POST /api/tasks/{id}/events/`

Create a new task event to track user interactions and system events during annotation.

    This endpoint is designed to receive events from the frontend labeling interface to enable
    accurate lead time calculation and detailed annotation analytics.

    ## Event Types

    **Core Annotation Events:**
    - `annotation_loaded` - When annotation interface is loaded
    - `annotation_created` - When annotation is submitted
    - `annotation_updated` - When annotation is modified
    - `annotation_reviewed` - When annotation is reviewed

    **User Activity Events:**
    - `visibility_change` - When page visibility changes (tab switch, minimize)
    - `idle_detected` - When user goes idle
    - `idle_resumed` - When user returns from idle

    **Interaction Events:**
    - `region_finished_drawing` - When annotation region is completed
    - `region_deleted` - When annotation regions are removed
    - `hotkey_pressed` - When keyboard shortcuts are used

    **Media Events:**
    - `video_playback_start/end` - Video playback control
    - `audio_playback_start/end` - Audio playback control
    - `video_scrub` - Video timeline scrubbing

    ## Usage

    Events are automatically associated with the task specified in the URL path.
    The current user is automatically set as the actor. Project and organization
    are derived from the task context.

    ## Example Request

    ```json
    {
        "event_key": "annotation_loaded",
        "event_time": "2024-01-15T10:30:00Z",
        "annotation": 123,
        "meta": {
            "annotation_count": 5,
            "estimated_time": 300
        }
    }
    ```

## Path parameters

- `id` integer, required

## Request body

- TaskEventRequest — Serializer for TaskEvent model to handle event creation from frontend. This serializer validates and processes task events sent from the labeling interface, ensuring proper data format and automatically setting required relationships.
  - `annotation` integer, nullable — Annotation ID associated with this event
  - `annotation_draft_id` integer, nullable — Draft annotation ID associated with this event
  - `event_key` string, required — Event type identifier (e.g., "annotation_loaded", "region_finished_drawing")
  - `event_time` string, date-time, required — Timestamp when the event occurred (frontend time)
  - `meta` unknown
  - `review` integer, nullable — Review ID associated with this event

## Response `201`

- TaskEvent — Serializer for TaskEvent model to handle event creation from frontend. This serializer validates and processes task events sent from the labeling interface, ensuring proper data format and automatically setting required relationships.
  - `actor` integer, required
  - `annotation` integer, nullable — Annotation ID associated with this event
  - `annotation_draft_id` integer, nullable — Draft annotation ID associated with this event
  - `created_at` string, date-time, required
  - `event_key` string, required — Event type identifier (e.g., "annotation_loaded", "region_finished_drawing")
  - `event_time` string, date-time, required — Timestamp when the event occurred (frontend time)
  - `id` integer, required
  - `meta` unknown
  - `organization` integer, required
  - `project` integer, required
  - `review` integer, nullable — Review ID associated with this event
  - `task` integer, required — Task this event is associated with

## Other responses

- `400` — Bad request - validation errors
- `401` — Unauthorized - authentication required
- `403` — Forbidden - insufficient permissions
- `404` — Not found - task does not exist

---

[API](https://skmtc.net/humansignal/apis/label-studio-api.md) · [All operations](https://skmtc.net/humansignal/apis/label-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humansignal/label-studio-api/revisions/1d13f90af57a/schema)