Bulk API

Bulk API

curl --request POST \
  --url https://text.external-api.pangram.com/bulk \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "items": [
    {}
  ],
  "text": [
    {}
  ]
}
'

import requests

url = "https://text.external-api.pangram.com/bulk"

payload = {
    "items": [{}],
    "text": [{}]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "bulk_id": "<string>",
  "status": "<string>",
  "total_items": 123,
  "accepted_items": [
    {}
  ],
  "failed_items": [
    {}
  ],
  "accepted": 123,
  "succeeded": 123,
  "failed": 123,
  "created_at": "<string>",
  "completed_at": "<string>",
  "offset": 123,
  "limit": 123,
  "items": [
    {}
  ]
}

POST

bulk

Bulk API

curl --request POST \
  --url https://text.external-api.pangram.com/bulk \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "items": [
    {}
  ],
  "text": [
    {}
  ]
}
'

import requests

url = "https://text.external-api.pangram.com/bulk"

payload = {
    "items": [{}],
    "text": [{}]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "bulk_id": "<string>",
  "status": "<string>",
  "total_items": 123,
  "accepted_items": [
    {}
  ],
  "failed_items": [
    {}
  ],
  "accepted": 123,
  "succeeded": 123,
  "failed": 123,
  "created_at": "<string>",
  "completed_at": "<string>",
  "offset": 123,
  "limit": 123,
  "items": [
    {}
  ]
}

Current

Bulk API

Current version

The Bulk API queues many AI detection inputs as one asynchronous job. Submit the job with POST /bulk, poll GET /bulk/{bulk_id}, then page through item metadata or results.

Completion time depends on the number and length of submitted items and current system load. Use GET /bulk/{bulk_id} to monitor progress. Bulk jobs use the same base URL and API key authentication as the AI detection task API:

https://text.external-api.pangram.com

Terminal bulk statuses are succeeded, failed, and partial. Bulk metadata and results are retained for 48 hours after the job reaches a terminal status. Timestamps are returned as Unix epoch seconds encoded as strings, such as "1760000000.0". Treat them as UTC instants when converting to a date-time value. The launch bulk limit is 1,000 billable units per request. A billable unit is one started 1,000-word block per valid item, with a minimum of one unit per item. There is no separate item-count limit, but normal request-body limits still apply. Requests over the current bulk limit return 413 Payload Too Large.

POST /bulk

Create a bulk AI detection job.

POST https://text.external-api.pangram.com/bulk

Request

Provide exactly one of items or text. Valid request bodies use either a plain text list:

{"text": ["First text", "Second text"]}

Or an items list when you want customer IDs returned with status and results:

{"items": [{"id": "row-001", "text": "First text"}]}

Do not include both text and items in the same request. Item id values are optional, but must be unique when provided.

items

array

List of item objects. Each item must include text and may include a unique customer-defined id.

text

array

List of input text strings. Use this simpler shape when you do not need customer item IDs.

Show Item object properties

string

Optional customer-defined item ID. IDs must be unique within the bulk request.

text

string

required

The input text to analyze.

Response

Returns 202 Accepted.

bulk_id

string

The ID of the bulk job.

status

string

Initial status. Usually queued; returns failed if every item failed immediate validation.

total_items

integer

Total number of submitted items.

accepted_items

array

Items accepted for processing. Each item includes index, optional id, and task_id.

failed_items

array

Items that failed immediate validation. Each item includes index, optional id, task_id: null, stage, and error.

Example

curl -X POST https://text.external-api.pangram.com/bulk \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "items": [
      {"id": "row-001", "text": "First text to analyze"},
      {"id": "row-002", "text": "Second text to analyze"}
    ]
  }'

from pangram import Pangram

client = Pangram()

bulk = client.submit_bulk(items=[
    {"id": "row-001", "text": "First text to analyze"},
    {"id": "row-002", "text": "Second text to analyze"},
])

bulk_id = bulk["bulk_id"]

Example Response

{
  "bulk_id": "blk_123",
  "status": "queued",
  "total_items": 2,
  "accepted_items": [
    {
      "index": 0,
      "id": "row-001",
      "task_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    {
      "index": 1,
      "id": "row-002",
      "task_id": "223e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "failed_items": []
}

GET /bulk/

Fetch the current status and counters for a bulk job.

GET https://text.external-api.pangram.com/bulk/{bulk_id}

Request

bulk_id

string

required

The bulk job ID returned by POST /bulk.

Response

bulk_id

string

The ID of the bulk job.

status

string

One of queued, running, succeeded, failed, or partial.

total_items

integer

Total number of submitted items.

accepted

integer

Number of items accepted for processing.

succeeded

integer

Number of items that completed successfully.

failed

integer

Number of items that failed.

created_at

string

Job creation timestamp as Unix epoch seconds encoded as a string.

completed_at

string

Job completion timestamp as Unix epoch seconds encoded as a string. null while the job is not terminal.

Example Response

{
  "bulk_id": "blk_123",
  "status": "partial",
  "total_items": 3,
  "accepted": 2,
  "succeeded": 2,
  "failed": 1,
  "created_at": "1760000000.0",
  "completed_at": "1760000030.0"
}

Status values

Status	Description
`queued`	The job was accepted, but no accepted item has started processing yet.
`running`	At least one accepted item is in progress and the job is not terminal.
`succeeded`	Every submitted item completed successfully.
`failed`	Every submitted item failed, including immediate validation failures.
`partial`	Every submitted item is terminal, with at least one success and at least one failure.

GET /bulk//items

Fetch paginated item metadata for a bulk job.

GET https://text.external-api.pangram.com/bulk/{bulk_id}/items?offset=0&limit=100

Request

bulk_id

string

required

The bulk job ID returned by POST /bulk.

offset

integer

default:"0"

Zero-based item offset.

limit

integer

default:"100"

Maximum number of items to return. The maximum is 1000.

Response

bulk_id

string

The ID of the bulk job.

offset

integer

The returned page offset.

limit

integer

The returned page limit.

total_items

integer

Total number of submitted items.

items

array

Item metadata. Each item includes index, optional id, task_id, stage, and optional error.

Example Response

{
  "bulk_id": "blk_123",
  "offset": 0,
  "limit": 100,
  "total_items": 2,
  "items": [
    {
      "index": 0,
      "id": "row-001",
      "task_id": "123e4567-e89b-12d3-a456-426614174000",
      "stage": "STAGE_SUCCESS",
      "error": null
    },
    {
      "index": 1,
      "id": "row-002",
      "task_id": null,
      "stage": "STAGE_FAILED",
      "error": "Text must contain at least one valid token"
    }
  ]
}

GET /bulk//results

Fetch paginated results for a bulk job.

GET https://text.external-api.pangram.com/bulk/{bulk_id}/results?offset=0&limit=100

Request

bulk_id

string

required

The bulk job ID returned by POST /bulk.

offset

integer

default:"0"

Zero-based item offset.

limit

integer

default:"100"

Maximum number of items to return. The maximum is 1000.

Response

bulk_id

string

The ID of the bulk job.

offset

integer

The returned page offset.

limit

integer

The returned page limit.

total_items

integer

Total number of submitted items.

items

array

Result items for successful or in-progress work. Successful completed items include result; in-progress items have result: null.

failed_items

array

Failed item metadata for the requested page.

Example Response

{
  "bulk_id": "blk_123",
  "offset": 0,
  "limit": 100,
  "total_items": 2,
  "items": [
    {
      "index": 0,
      "id": "row-001",
      "task_id": "123e4567-e89b-12d3-a456-426614174000",
      "stage": "STAGE_SUCCESS",
      "error": null,
      "result": {
        "text": "First text to analyze",
        "version": "3.3",
        "prediction": "We believe this is human-written",
        "prediction_short": "Human",
        "fraction_ai": 0.0,
        "fraction_ai_assisted": 0.0,
        "fraction_human": 1.0,
        "headline": "Human Written",
        "num_ai_segments": 0,
        "num_ai_assisted_segments": 0,
        "num_human_segments": 1,
        "windows": []
      }
    }
  ],
  "failed_items": [
    {
      "index": 1,
      "id": "row-002",
      "task_id": null,
      "stage": "STAGE_FAILED",
      "error": "Text must contain at least one valid token"
    }
  ]
}

Errors

Status Code	Description
`401 Unauthorized`	The `x-api-key` is missing or invalid.
`402 Payment Required`	The account has insufficient credits.
`403 Forbidden`	The API key does not own the requested bulk job.
`404 Not Found`	The requested bulk job does not exist.
`413 Payload Too Large`	The bulk request exceeds the maximum billable units.
`422 Unprocessable Entity`	The request is empty, contains both `items` and `text`, includes duplicate item IDs, or otherwise fails validation.
`500 Internal Server Error`	There was an error processing the request.

AI Detection File Upload

REST API

Deprecated

POST /bulk

Request

Response

Example

GET /bulk/

Request

Response

Status values

GET /bulk//items

Request

Response

GET /bulk//results

Request

Response

Errors

​POST /bulk

​Request

​Response

​Example

​GET /bulk/

​Request

​Response

​Status values

​GET /bulk//items

​Request

​Response

​GET /bulk//results

​Request

​Response

​Errors

POST /bulk

Request

Response

Example

GET /bulk/

Request

Response

Status values

GET /bulk//items

Request

Response

GET /bulk//results

Request

Response

Errors