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: 30 seconds per SQL query

Result Set Cap: 100 rows by default; an explicit larger LIMIT is clamped to 5,000. Scalar aggregates return 1 row.

Dataset Scoping: Up to 10 datasets per chat request

Information

SQL queries that exceed 30 seconds are terminated. The agent can make up to 15 iterations (tool calls) to answer complex questions. A query with no explicit LIMIT returns 100 rows; a larger explicit LIMIT is clamped to 5,000.

json
{
"error_code": "internal_error",
"message": "Query execution timeout after 30 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: