Common Patterns - Extralt Docs

Polling a run

Runs are asynchronous. After creating a run, poll its status until it reaches a terminal state (completed, failed, or stopped).

curl -s "https://api.extralt.com/runs/$RUN_ID" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" | jq '.status'

A 10-second polling interval is a reasonable default. For long-running extractions, you can increase it to 30 seconds.

Handling errors

The API returns standard HTTP status codes. Wrap requests with error handling:

# Check the HTTP status code in the response
HTTP_STATUS=$(curl -s -o response.json -w "%{http_code}" \
  -X POST "$BASE_URL/runs" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"robotId\": \"$ROBOT_ID\", \"urls\": [\"$URL\"]}")

if [ "$HTTP_STATUS" -eq 429 ]; then
  echo "Rate limited, retrying in 15s..."
  sleep 15
  curl -s -X POST "$BASE_URL/runs" \
    -H "Authorization: Bearer $EXTRALT_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"robotId\": \"$ROBOT_ID\", \"urls\": [\"$URL\"]}" | jq
elif [ "$HTTP_STATUS" -ge 400 ]; then
  echo "Error ($HTTP_STATUS):"
  jq '.message' response.json
else
  jq '.' response.json
fi

See Error Codes for the complete error catalog.

Pagination

When listing captures, results may be paginated for large result sets. Use cursor-based pagination:

# First page
curl -s "$BASE_URL/captures?runId=$RUN_ID" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" | jq

# Subsequent pages — pass the nextCursor from the previous response
curl -s "$BASE_URL/captures?runId=$RUN_ID&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $EXTRALT_API_KEY" | jq

Rate limit handling

The API allows approximately 120 requests per minute sustained, with a burst of 30 requests. When rate limited, you receive a 429 response.

The simplest strategy: wait 15 seconds to refill burst capacity, then retry.

# Retry once after a 429 response
HTTP_STATUS=$(curl -s -o response.json -w "%{http_code}" \
  "$BASE_URL/runs/$RUN_ID" \
  -H "Authorization: Bearer $EXTRALT_API_KEY")

if [ "$HTTP_STATUS" -eq 429 ]; then
  echo "Rate limited, retrying in 15s..."
  sleep 15
  curl -s "$BASE_URL/runs/$RUN_ID" \
    -H "Authorization: Bearer $EXTRALT_API_KEY" | jq
else
  jq '.' response.json
fi

See Rate Limits for full details.