> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Tasks by External Source ID

> Find the tasks linked to a record in an external system

Looks up tasks by the external source identifier recorded on them, so you can resolve one of your own
records back to the Chamelio tasks it produced.

## Endpoint

```
GET /tasks/by-external-source-id
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

## Query Parameters

| Parameter            | Type   | Required | Description                                                          |
| -------------------- | ------ | -------- | -------------------------------------------------------------------- |
| `external_source_id` | string | Yes      | The external source identifier to filter tasks by. Must not be empty |

<Info>
  External source IDs are assigned by whichever system created the task. This endpoint only reads them -
  there is no API field for setting one.
</Info>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/tasks/by-external-source-id?external_source_id=OPP-00123" \
    -H "X-API-Key: ca_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  url = "https://platform.chamelio.ai/tasks/by-external-source-id"
  headers = {
      "X-API-Key": "ca_your_api_key_here"
  }
  params = {
      "external_source_id": "OPP-00123"
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    external_source_id: 'OPP-00123'
  });

  const response = await fetch(
    `https://platform.chamelio.ai/tasks/by-external-source-id?${params}`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': 'ca_your_api_key_here'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "tasks": [
    {
      "task_id": 12345,
      "task_url": "https://app.chamelio.ai/workflows/tasks/12345",
      "task_title": "Vendor Contract Review - Acme Corporation",
      "workflow_id": "vendor_contract_review",
      "workflow_name": "Vendor Contract Review",
      "workflow_version": 1,
      "workflow_state_id": "ws_abc123",
      "status": "in_progress",
      "priority": "high",
      "current_step_run_id": "sr_002",
      "current_step_id": "review_step",
      "current_step_name": "AI Review",
      "current_step_type": "review",
      "created_at": "2025-01-20T10:30:00Z",
      "updated_at": "2025-01-20T10:35:00Z",
      "completed_at": null,
      "owner_email": "john.doe@example.com",
      "assignee_email": "legal@example.com",
      "collaborator_emails": [],
      "requester_email": "john.doe@example.com",
      "step_runs": [],
      "variables": []
    }
  ]
}
```

### Response Fields

| Field   | Type  | Description                                |
| ------- | ----- | ------------------------------------------ |
| `tasks` | array | Matching tasks. Empty when nothing matches |

### Task Object Fields

Each entry is a task object, the same shape returned by
[Get Task](/api-reference/endpoint/tasks/get). See that page for the full field list, including the
`step_runs` and `variables` structures.

## Error Responses

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/api-keys#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 422 Validation Error

Returned when `external_source_id` is missing or empty.

```json theme={null}
{
  "detail": [
    {
      "loc": ["query", "external_source_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### 500 Internal Server Error

Returned when the request fails due to a server error.

```json theme={null}
{
  "detail": "Failed to get tasks"
}
```

## Notes

<Info>
  An external source ID can match more than one task, so `tasks` is always an array. A source ID with no
  matching tasks returns an empty array rather than a `404`.
</Info>

## Use Cases

* **Cross-system lookup** - Jump from a record in your own system to its Chamelio tasks
* **Deduplication** - Check whether a record already produced a task before creating another
* **Status embedding** - Show Chamelio task status inside your own record view