> ## 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 /v2/tasks/by-external-source-id
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `tasks:read`

## 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/v2/tasks/by-external-source-id?external_source_id=OPP-00123" \
    -H "Authorization: Bearer your_access_token"
  ```

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

  url = "https://platform.chamelio.ai/v2/tasks/by-external-source-id"
  headers = {
      "Authorization": "Bearer your_access_token"
  }
  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/v2/tasks/by-external-source-id?${params}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer your_access_token'
      }
    }
  );

  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 the user is allowed to see. Empty when nothing matches |

### Task Object Fields

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

## Error Responses

### 400 Bad Request

Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.

```json theme={null}
{
  "detail": "client_credentials tokens are not associated with a user"
}
```

### 401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token does not carry the required scope.

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: tasks:read"
}
```

### 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"
    }
  ]
}
```

### 429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 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>

<Info>
  Only tasks the access token's user is allowed to see are returned, so the same source ID can yield
  different results for different users.
</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