ParseSphereParseSphere

Rate Limits & Quotas

These limits protect system stability and ensure consistent performance across all users.

File Size Limits

ParseSphere enforces maximum file sizes for different operations:

Document Parsing: Files up to 200 MB

Workspace File Uploads: Files up to 200 MB

Warning

Requests exceeding these limits return a 413 status code before any processing occurs.

json
{
"error_code": "file_too_large",
"message": "File too large (250.0MB). Maximum allowed: 200MB",
"details": {
  "file_size_mb": 55.0,
  "max_size_mb": 50
},
"request_id": "req_abc123",
"timestamp": "2025-01-03T10:30:00Z"
}

Working with Large Files

For files exceeding size limits, consider compressing the document or splitting it into smaller parts before upload.

Workspace Limits

Workspaces have the following constraints:

Maximum File Size: 200 MB per file

json
{
"error_code": "workspace_limit_exceeded",
"message": "Workspace has reached maximum table limit (50 tables). Please delete existing tables or upgrade your plan.",
"details": {
  "current_count": 50,
  "maximum": 50
},
"request_id": "req_ghi789",
"timestamp": "2025-01-03T10:30:00Z"
}

Chat & Query Limits

Natural language chat has the following constraints:

Maximum Iterations: 15 per message (configurable, 1-20)

Message Length: 10,000 characters maximum

Query Execution Timeout: 60 seconds per SQL query

Result Set Cap: 1,000 rows per SQL query

Dataset Scoping: Up to 10 datasets per chat request

Information

SQL queries that exceed 60 seconds are terminated. The agent can make up to 15 iterations (tool calls) to answer complex questions. Individual query results are capped at 1,000 rows.

json
{
"error_code": "internal_error",
"message": "Query execution timeout after 60 seconds",
"request_id": "req_jkl012",
"timestamp": "2025-01-03T10:30:00Z"
}

Tip

If queries timeout, try being more specific in your question or use aggregations. The chat interface allows you to refine your question with follow-ups.

Result Caching

Parse results remain cached for efficient retrieval:

Default Cache Duration: 30 minutes

Configurable Range: 60 seconds to 86,400 seconds (24 hours)

Behavior: Subsequent requests for the same parse_id return cached results without reprocessing.

Configure Cache Duration

Override the default duration with the session_ttl parameter:

bash
curl -X POST https://api.parsesphere.com/v1/parses \
-H "Authorization: Bearer sk_your_api_key" \
-F "file=@document.pdf" \
-F "session_ttl=300"  # 5 minutes

Shorter TTLs reduce storage costs for high-volume integrations

Longer TTLs improve response times for frequently accessed documents

API Versioning

The current API version is v1, specified in the URL path:

bash
# All endpoints use /v1/ in the path
https://api.parsesphere.com/v1/parses
https://api.parsesphere.com/v1/workspaces
https://api.parsesphere.com/v1/api-keys

Version Policy

Information

Version increments (v2, v3) occur only for breaking changes—removed endpoints, changed response structures, or altered parameter semantics.

Breaking changes that trigger new versions:

  • Removed endpoints
  • Changed response structures
  • Altered parameter semantics

Non-breaking changes shipped within existing versions:

  • New optional parameters
  • Additional response fields
  • New endpoints

Warning

Monitor the changelog for deprecation notices before version transitions. We provide advance notice for all breaking changes.

What's Next?

Learn more about API usage: