Add external_id to Task API and SDK

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: snopoke

taskbadger.yaml

@@ -694,6 +694,11 @@ components:
           type: string
           description: Queue the task is from
           maxLength: 255
+        external_id:
+          type: string
+          description: Identifier from the originating system (e.g. Celery task ID)
+            for correlating with logs
+          maxLength: 255
         status:
           allOf:
           - $ref: '#/components/schemas/StatusEnum'
@@ -794,6 +799,11 @@ components:
           type: string
           description: Queue the task is from
           maxLength: 255
+        external_id:
+          type: string
+          description: Identifier from the originating system (e.g. Celery task ID)
+            for correlating with logs
+          maxLength: 255
         status:
           allOf:
           - $ref: '#/components/schemas/StatusEnum'
@@ -893,6 +903,11 @@ components:
           type: string
           description: Queue the task is from
           maxLength: 255
+        external_id:
+          type: string
+          description: Identifier from the originating system (e.g. Celery task ID)
+            for correlating with logs
+          maxLength: 255
         status:
           allOf:
           - $ref: '#/components/schemas/StatusEnum'

taskbadger/internal/models/patched_task_request.py

@@ -24,6 +24,8 @@ class PatchedTaskRequest:
     Attributes:
         name (str | Unset): Name of the task
         queue (str | Unset): Queue the task is from
+        external_id (str | Unset): Identifier from the originating system (e.g. Celery task ID) for correlating with
+            logs
         status (StatusEnum | Unset): * `pending` - pending
             * `pre_processing` - pre_processing
             * `processing` - processing
@@ -50,6 +52,7 @@ class PatchedTaskRequest:
 
     name: str | Unset = UNSET
     queue: str | Unset = UNSET
+    external_id: str | Unset = UNSET
     status: StatusEnum | Unset = StatusEnum.PENDING
     value: int | None | Unset = UNSET
     value_max: int | Unset = UNSET
@@ -69,6 +72,8 @@ def to_dict(self) -> dict[str, Any]:
 
         queue = self.queue
 
+        external_id = self.external_id
+
         status: str | Unset = UNSET
         if not isinstance(self.status, Unset):
             status = self.status.value
@@ -128,6 +133,8 @@ def to_dict(self) -> dict[str, Any]:
             field_dict["name"] = name
         if queue is not UNSET:
             field_dict["queue"] = queue
+        if external_id is not UNSET:
+            field_dict["external_id"] = external_id
         if status is not UNSET:
             field_dict["status"] = status
         if value is not UNSET:
@@ -160,6 +167,8 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
 
         queue = d.pop("queue", UNSET)
 
+        external_id = d.pop("external_id", UNSET)
+
         _status = d.pop("status", UNSET)
         status: StatusEnum | Unset
         if isinstance(_status, Unset):
@@ -251,6 +260,7 @@ def _parse_stale_timeout(data: object) -> int | None | Unset:
         patched_task_request = cls(
             name=name,
             queue=queue,
+            external_id=external_id,
             status=status,
             value=value,
             value_max=value_max,

taskbadger/internal/models/task.py

@@ -32,6 +32,8 @@ class Task:
         url (str):
         public_url (str):
         queue (str | Unset): Queue the task is from
+        external_id (str | Unset): Identifier from the originating system (e.g. Celery task ID) for correlating with
+            logs
         status (StatusEnum | Unset): * `pending` - pending
             * `pre_processing` - pre_processing
             * `processing` - processing
@@ -66,6 +68,7 @@ class Task:
     url: str
     public_url: str
     queue: str | Unset = UNSET
+    external_id: str | Unset = UNSET
     status: StatusEnum | Unset = StatusEnum.PENDING
     value: int | None | Unset = UNSET
     value_max: int | Unset = UNSET
@@ -102,6 +105,8 @@ def to_dict(self) -> dict[str, Any]:
 
         queue = self.queue
 
+        external_id = self.external_id
+
         status: str | Unset = UNSET
         if not isinstance(self.status, Unset):
             status = self.status.value
@@ -171,6 +176,8 @@ def to_dict(self) -> dict[str, Any]:
         )
         if queue is not UNSET:
             field_dict["queue"] = queue
+        if external_id is not UNSET:
+            field_dict["external_id"] = external_id
         if status is not UNSET:
             field_dict["status"] = status
         if value is not UNSET:
@@ -224,6 +231,8 @@ def _parse_value_percent(data: object) -> int | None:
 
         queue = d.pop("queue", UNSET)
 
+        external_id = d.pop("external_id", UNSET)
+
         _status = d.pop("status", UNSET)
         status: StatusEnum | Unset
         if isinstance(_status, Unset):
@@ -323,6 +332,7 @@ def _parse_stale_timeout(data: object) -> int | None | Unset:
             url=url,
             public_url=public_url,
             queue=queue,
+            external_id=external_id,
             status=status,
             value=value,
             value_max=value_max,

taskbadger/internal/models/task_request.py

@@ -24,6 +24,8 @@ class TaskRequest:
     Attributes:
         name (str): Name of the task
         queue (str | Unset): Queue the task is from
+        external_id (str | Unset): Identifier from the originating system (e.g. Celery task ID) for correlating with
+            logs
         status (StatusEnum | Unset): * `pending` - pending
             * `pre_processing` - pre_processing
             * `processing` - processing
@@ -50,6 +52,7 @@ class TaskRequest:
 
     name: str
     queue: str | Unset = UNSET
+    external_id: str | Unset = UNSET
     status: StatusEnum | Unset = StatusEnum.PENDING
     value: int | None | Unset = UNSET
     value_max: int | Unset = UNSET
@@ -69,6 +72,8 @@ def to_dict(self) -> dict[str, Any]:
 
         queue = self.queue
 
+        external_id = self.external_id
+
         status: str | Unset = UNSET
         if not isinstance(self.status, Unset):
             status = self.status.value
@@ -130,6 +135,8 @@ def to_dict(self) -> dict[str, Any]:
         )
         if queue is not UNSET:
             field_dict["queue"] = queue
+        if external_id is not UNSET:
+            field_dict["external_id"] = external_id
         if status is not UNSET:
             field_dict["status"] = status
         if value is not UNSET:
@@ -162,6 +169,8 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
 
         queue = d.pop("queue", UNSET)
 
+        external_id = d.pop("external_id", UNSET)
+
         _status = d.pop("status", UNSET)
         status: StatusEnum | Unset
         if isinstance(_status, Unset):
@@ -253,6 +262,7 @@ def _parse_stale_timeout(data: object) -> int | None | Unset:
         task_request = cls(
             name=name,
             queue=queue,
+            external_id=external_id,
             status=status,
             value=value,
             value_max=value_max,

taskbadger/sdk.py

@@ -152,6 +152,7 @@ def create_task(
     monitor_id: str = None,
     tags: dict[str, str] = None,
     queue: str = None,
+    external_id: str = None,
 ) -> "Task":
     """Create a Task.
 
@@ -167,6 +168,7 @@ def create_task(
         monitor_id: ID of the monitor to associate this task with.
         tags: Dictionary of namespace -> value tags.
         queue: Name of the queue the task is from.
+        external_id: Identifier from the originating system (e.g. Celery task ID) for correlating with logs.
 
     Returns:
         Task: The created Task object.
@@ -177,6 +179,8 @@ def create_task(
     }
     if queue is not None:
         task_dict["queue"] = queue
+    if external_id is not None:
+        task_dict["external_id"] = external_id
     if value is not None:
         task_dict["value"] = value
     if value_max is not None:
@@ -222,6 +226,7 @@ def update_task(
     actions: list[Action] = None,
     tags: dict[str, str] = None,
     queue: str = None,
+    external_id: str = None,
 ) -> "Task":
     """Update a task.
     Requires only the task ID and fields to update.
@@ -238,6 +243,7 @@ def update_task(
         actions: Task actions. **Deprecated:** use project-level actions instead.
         tags: Dictionary of namespace -> value tags.
         queue: Name of the queue the task is from.
+        external_id: Identifier from the originating system (e.g. Celery task ID) for correlating with logs.
 
     Returns:
         Task: The updated Task object.
@@ -250,6 +256,7 @@ def update_task(
     max_runtime = _none_to_unset(max_runtime)
     stale_timeout = _none_to_unset(stale_timeout)
     queue = _none_to_unset(queue)
+    external_id = _none_to_unset(external_id)
 
     data = data or UNSET
     body = PatchedTaskRequest(
@@ -261,6 +268,7 @@ def update_task(
         max_runtime=max_runtime,
         stale_timeout=stale_timeout,
         queue=queue,
+        external_id=external_id,
     )
     if actions:
         _warn_actions_deprecated()
@@ -335,6 +343,7 @@ def create(
         monitor_id: str = None,
         tags: dict[str, str] = None,
         queue: str = None,
+        external_id: str = None,
     ) -> "Task":
         """Create a new task
 
@@ -352,6 +361,7 @@ def create(
             monitor_id=monitor_id,
             tags=tags,
             queue=queue,
+            external_id=external_id,
         )
 
     def __init__(self, task):
@@ -437,6 +447,7 @@ def update(
         actions: list[Action] = None,
         tags: dict[str, str] = None,
         queue: str = None,
+        external_id: str = None,
         data_merge_strategy: Any = None,
     ):
         """Generic update method used to update any of the task fields.
@@ -465,6 +476,7 @@ def update(
             actions=actions,
             tags=tags,
             queue=queue,
+            external_id=external_id,
         )
         self._task = task._task
 

tests/test_sdk.py

@@ -124,6 +124,31 @@ def test_update_queue(settings, patched_update):
     _verify_update(settings, patched_update, queue="high_priority")
 
 
+def test_create_with_external_id(settings, patched_create):
+    api_task = task_for_test()
+    patched_create.return_value = Response(HTTPStatus.OK, b"", {}, api_task)
+
+    Task.create(name="task name", external_id="celery-abc-123")
+
+    request = TaskRequest(name="task name", status=StatusEnum.PENDING, external_id="celery-abc-123")
+    patched_create.assert_called_with(
+        client=mock.ANY,
+        organization_slug="org",
+        project_slug="project",
+        body=request,
+    )
+
+
+def test_update_external_id(settings, patched_update):
+    api_task = task_for_test()
+    task = Task(api_task)
+
+    patched_update.return_value = Response(HTTPStatus.OK, b"", {}, api_task)
+    task.update(external_id="celery-abc-123")
+
+    _verify_update(settings, patched_update, external_id="celery-abc-123")
+
+
 def test_before_create_update_task(settings, patched_create):
     def before_create(task):
         tags = task.setdefault("tags", {})