Processing Priority

Introduction

When submitting drawing requests to the Werk24 API, each request is assigned a processing priority that determines its position in the processing queue. Understanding priorities helps you optimize your workflow, especially when handling both time-sensitive and batch processing tasks.

What Is Processing Priority?

Processing priority determines the order in which drawing requests are processed by the Werk24 API. Higher priority requests are picked up before lower priority ones, allowing time-sensitive work to complete faster while batch jobs can be queued at lower priority.

The Werk24 API has three priority levels. Each is a promise on how soon a request is picked up (99th percentile), not on how long the read itself takes:

Level	Value	Pickup (p99)	How you get it
Best-effort	`PRIO3`	within 10 minutes	Included on every plan, Pay as You Go and Production among them
Priority	`PRIO2`	within 60 seconds	An add-on on Production (and on the retired Essential and Growth plans), or part of a contract
Express	`PRIO1`	within 10 seconds	An add-on on Production (and on the retired Essential and Growth plans), or part of a contract

The pickup time counts from when one of your slots is free. A request sent while all of them are busy first waits for one of your own requests to finish, and that wait is not part of the promise.

werk24.io/pricing lists the add-ons and their prices. Accounts on the retired Essential and Growth plans keep the level they had.

Your Account's Level and Priority

Your account's level is the highest priority you can ask for:

Express (PRIO1): can use PRIO1, PRIO2 or PRIO3
Priority (PRIO2): can use PRIO2 or PRIO3
Best-effort (PRIO3): can only use PRIO3

By default, requests use your account's level. The priority override lets you use a lower one, for example to keep a batch out of the way of your own interactive requests. To ask for a higher one, book the Priority or Express add-on first; until then the API refuses it with PRIORITY_TOO_HIGH.

Why Use Priority Override?

Priority override is useful when you want to:

Batch Processing: Queue large volumes of drawings at lower priority without impacting your real-time requests
Resource Management: Separate urgent work from background tasks
Fair Queuing: Allow other users' urgent requests to process while your batch jobs wait

The page rate is the same whatever the priority, so a lower priority does not make a read cheaper.

Using Priority Override

Basic Usage with read_drawing()

import asyncio
from werk24 import Werk24Client, AskMetaData

async def process_drawing_with_priority():
    async with Werk24Client() as client:
        with open("drawing.pdf", "rb") as f:
            # Process with default priority (account tier)
            async for message in client.read_drawing(f, [AskMetaData()]):
                print(message)

            # Process with explicit lower priority
            f.seek(0)  # Reset file position
            async for message in client.read_drawing(
                f, 
                [AskMetaData()], 
                priority="PRIO3"  # Use lowest priority for batch
            ):
                print(message)

asyncio.run(process_drawing_with_priority())

Using with Hooks

import asyncio
from werk24 import Werk24Client, AskMetaData, Hook, TechreadMessage

def handle_result(message: TechreadMessage):
    if message.is_successful:
        print(f"Processed: {message.payload_dict}")

async def batch_process():
    hooks = [Hook(ask=AskMetaData(), function=handle_result)]

    async with Werk24Client() as client:
        with open("drawing.pdf", "rb") as f:
            # Use PRIO3 for batch processing
            await client.read_drawing_with_hooks(
                f, 
                hooks, 
                priority="PRIO3"
            )

asyncio.run(batch_process())

Using with Callbacks

import asyncio
from werk24 import Werk24Client, AskMetaData

async def submit_batch_job():
    async with Werk24Client() as client:
        with open("drawing.pdf", "rb") as f:
            request_id = await client.read_drawing_with_callback(
                f,
                asks=[AskMetaData()],
                callback_url="https://your-server.com/webhook",
                priority="PRIO3"  # Lower priority for batch
            )
            print(f"Submitted batch job: {request_id}")

asyncio.run(submit_batch_job())

Using CURL with Callbacks

You can also submit callback requests directly via the REST API with a priority override:

curl -X POST "https://api.w24.co/techread/read-with-callback" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "drawing=@drawing.pdf" \
  -F "asks=[{\"ask_version\": \"v2\", \"ask_type\": \"META_DATA\"}]" \
  -F "callback_url=https://your-server.com/webhook" \
  -F "max_pages=5" \
  -F "priority=PRIO3"

The response contains the request ID for tracking:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Your callback endpoint will receive the results once processing completes.

curl sends the drawing inside the request body, so the callback size limit of about 4.6 MB applies, and nothing checks it before the upload: a larger drawing is refused without a request_id. See Drawing File Size Limit.

Priority Values Are Case-Insensitive

The client accepts priority values in any case:

# All of these are equivalent
priority="PRIO1"
priority="prio1"
priority="Prio1"

The client normalizes the value to uppercase before sending to the server.

Error Handling

PriorityTooHighError

This exception is raised when you request a priority higher than your account tier allows.

import asyncio
from werk24 import Werk24Client, AskMetaData, PriorityTooHighError

async def handle_priority_error():
    async with Werk24Client() as client:
        try:
            with open("drawing.pdf", "rb") as f:
                async for message in client.read_drawing(
                    f, 
                    [AskMetaData()], 
                    priority="PRIO1"  # May fail if account is PRIO2 or PRIO3
                ):
                    print(message)
        except PriorityTooHighError as e:
            print(f"Priority too high!")
            print(f"Your account tier: {e.account_tier}")
            print(f"Requested priority: {e.requested_priority}")
            print(f"Try using priority='{e.account_tier}' or lower")

asyncio.run(handle_priority_error())

Exception attributes:

account_tier: Your account's maximum allowed priority (e.g., "PRIO2")
requested_priority: The priority you attempted to use (e.g., "PRIO1")

InvalidPriorityError

This exception is raised when you provide an invalid priority value.

import asyncio
from werk24 import Werk24Client, AskMetaData, InvalidPriorityError

async def handle_invalid_priority():
    async with Werk24Client() as client:
        try:
            with open("drawing.pdf", "rb") as f:
                async for message in client.read_drawing(
                    f, 
                    [AskMetaData()], 
                    priority="INVALID"  # Not a valid priority
                ):
                    print(message)
        except InvalidPriorityError as e:
            print(f"Invalid priority value: {e.invalid_value}")
            print("Valid values are: PRIO1, PRIO2, PRIO3")

asyncio.run(handle_invalid_priority())

Exception attributes:

invalid_value: The invalid priority string you provided

Best Practices

1. Use Default Priority for Interactive Requests

For user-facing applications where response time matters, don't specify a priority; let it default to your account's maximum:

# Good: Uses account's default priority
async for message in client.read_drawing(f, asks):
    process(message)

2. Use PRIO3 for Batch Processing

When processing large volumes of drawings in the background:

# Good: Explicitly use lowest priority for batch
async for message in client.read_drawing(f, asks, priority="PRIO3"):
    process(message)

3. Handle Priority Errors Gracefully

Always catch priority-related exceptions in production code:

from werk24 import PriorityTooHighError, InvalidPriorityError

try:
    async for message in client.read_drawing(f, asks, priority=user_priority):
        process(message)
except PriorityTooHighError as e:
    # Fall back to account tier
    async for message in client.read_drawing(f, asks, priority=e.account_tier):
        process(message)
except InvalidPriorityError as e:
    logger.error(f"Invalid priority '{e.invalid_value}' - using default")
    async for message in client.read_drawing(f, asks):
        process(message)

4. Separate Queues by Priority

For applications with mixed workloads, consider separating requests by priority:

async def process_urgent(drawing_path: str):
    """Process urgent requests at default (highest) priority."""
    async with Werk24Client() as client:
        with open(drawing_path, "rb") as f:
            async for message in client.read_drawing(f, asks):
                yield message

async def process_batch(drawing_paths: list[str]):
    """Process batch requests at lowest priority."""
    async with Werk24Client() as client:
        for path in drawing_paths:
            with open(path, "rb") as f:
                async for message in client.read_drawing(f, asks, priority="PRIO3"):
                    yield message