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

# AI Detection

> Detect AI-generated and AI-assisted text using the async inference API

<Badge color="green">Current</Badge>

<Update label="Async inference API" description="Current version">
  The current AI detection API creates an async task and returns a task ID. Poll the task endpoint until it reaches `STAGE_SUCCESS` or `STAGE_FAILED`.
</Update>

Use the [Bulk API](/api-reference/bulk-api) when you need to analyze many texts as one asynchronous job.

## POST /task

Create an async AI detection task.

```
POST https://text.external-api.pangram.com/task
```

### Request

<ParamField body="text" type="string" required>
  The input text to analyze.
</ParamField>

<ParamField body="public_dashboard_link" type="boolean" default="false">
  Whether to include a public dashboard link in the completed response.
</ParamField>

### Response

<ResponseField name="task_id" type="string">
  The ID of the async inference task.
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://text.external-api.pangram.com/task \
    -H "Content-Type: application/json" \
    -H "x-api-key: your_api_key_here" \
    -d '{
      "text": "The text to analyze with Pangram",
      "public_dashboard_link": false
    }'
  ```

  ```python Python SDK theme={null}
  from pangram import Pangram

  pangram_client = Pangram()
  result = pangram_client.predict("The text to analyze with Pangram")
  ```
</CodeGroup>

**Example Response**

```json theme={null}
{
  "task_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

***

## GET /task/{task_id}

Fetch the current status or completed result for an AI detection task.

```
GET https://text.external-api.pangram.com/task/{task_id}
```

### Request

<ParamField path="task_id" type="string" required>
  The task ID returned by `POST /task`.
</ParamField>

### Response

<ResponseField name="task_id" type="string">
  The ID of the async inference task. Present while the task is in progress.
</ResponseField>

<ResponseField name="stage" type="string">
  Current task stage. Terminal stages are `STAGE_SUCCESS` and `STAGE_FAILED`.
</ResponseField>

<ResponseField name="text" type="string">
  The input text that was analyzed. Present on success.
</ResponseField>

<ResponseField name="version" type="string">
  The API version identifier (e.g., `"3.0"`). Present on success.
</ResponseField>

<ResponseField name="headline" type="string">
  Classification headline summarizing the result. Present on success.
</ResponseField>

<ResponseField name="prediction" type="string">
  Long-form prediction string describing the classification. Present on success.
</ResponseField>

<ResponseField name="prediction_short" type="string">
  Short-form prediction string (e.g., `"AI"`, `"AI-Assisted"`, `"Human"`, `"Mixed"`). Present on success.
</ResponseField>

<ResponseField name="fraction_ai" type="float">
  Fraction of text classified as AI-written (0.0–1.0). Present on success.
</ResponseField>

<ResponseField name="fraction_ai_assisted" type="float">
  Fraction of text classified as AI-assisted (0.0–1.0). Present on success.
</ResponseField>

<ResponseField name="fraction_human" type="float">
  Fraction of text classified as human-written (0.0–1.0). Present on success.
</ResponseField>

<ResponseField name="num_ai_segments" type="integer">
  Number of text segments classified as AI. Present on success.
</ResponseField>

<ResponseField name="num_ai_assisted_segments" type="integer">
  Number of text segments classified as AI-assisted. Present on success.
</ResponseField>

<ResponseField name="num_human_segments" type="integer">
  Number of text segments classified as human. Present on success.
</ResponseField>

<ResponseField name="dashboard_link" type="string">
  A link to the dashboard page containing the full classification result. Present on success when `public_dashboard_link` is `true`.
</ResponseField>

<ResponseField name="windows" type="array">
  List of text segments (<Tooltip tip="The text is divided into overlapping segments (windows) that are each classified independently, enabling granular detection across long documents.">windows</Tooltip>) analyzed individually. Present on success.

  <Expandable title="Window object properties">
    <ResponseField name="text" type="string">
      The window text.
    </ResponseField>

    <ResponseField name="label" type="string">
      Descriptive classification label (e.g., `"AI-Generated"`, `"Moderately AI-Assisted"`).
    </ResponseField>

    <ResponseField name="ai_assistance_score" type="float">
      <Tooltip tip="A continuous score from 0 to 1, where 0 means entirely human-written and 1 means fully AI-generated. Values in between indicate varying degrees of AI assistance.">AI assistance score</Tooltip> detailing the level of AI assistance (0.0–1.0).
    </ResponseField>

    <ResponseField name="confidence" type="string">
      <Tooltip tip="High = strong signal, the model is very sure. Medium = moderate signal. Low = weak signal, treat with caution.">Confidence level</Tooltip> for the classification (`"High"`, `"Medium"`, `"Low"`).
    </ResponseField>

    <ResponseField name="start_index" type="integer">
      Starting character index in the original text.
    </ResponseField>

    <ResponseField name="end_index" type="integer">
      Ending character index in the original text.
    </ResponseField>

    <ResponseField name="word_count" type="integer">
      Number of words in the window.
    </ResponseField>

    <ResponseField name="token_length" type="integer">
      Token length of the window.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash cURL theme={null}
curl -X GET https://text.external-api.pangram.com/task/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: your_api_key_here"
```

**In-Progress Response**

```json theme={null}
{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "stage": "STAGE_PREPROCESSING"
}
```

**Success Response**

```json theme={null}
{
  "stage": "STAGE_SUCCESS",
  "text": "The text to analyze with Pangram",
  "version": "3.0",
  "headline": "AI Detected",
  "prediction": "We are confident that this document contains AI-generated or AI-assisted content.",
  "prediction_short": "Mixed",
  "fraction_ai": 0.70,
  "fraction_ai_assisted": 0.20,
  "fraction_human": 0.10,
  "num_ai_segments": 7,
  "num_ai_assisted_segments": 2,
  "num_human_segments": 1,
  "dashboard_link": "https://www.pangram.com/history/123e4567-e89b-12d3-a456-426614174000",
  "windows": [
    {
      "text": "The text to analyze",
      "label": "AI-Generated",
      "ai_assistance_score": 0.85,
      "confidence": "High",
      "start_index": 0,
      "end_index": 19,
      "word_count": 4,
      "token_length": 5
    },
    {
      "text": "with Pangram",
      "label": "Moderately AI-Assisted",
      "ai_assistance_score": 0.45,
      "confidence": "Medium",
      "start_index": 20,
      "end_index": 32,
      "word_count": 2,
      "token_length": 3
    }
  ]
}
```

**Failed Response**

```json theme={null}
{
  "stage": "STAGE_FAILED",
  "text": "",
  "version": "",
  "headline": "preprocessing: Input text contains no valid text after preprocessing",
  "prediction": "",
  "prediction_short": "",
  "fraction_ai": 0.0,
  "fraction_ai_assisted": 0.0,
  "fraction_human": 0.0,
  "num_ai_segments": 0,
  "num_ai_assisted_segments": 0,
  "num_human_segments": 0,
  "windows": []
}
```