Skip to main content
POST
/
api
/
v2
/
parsing-status
curl --request POST \
  --url https://production-api.potpie.ai/api/v2/parsing-status \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "repo_name": "my-awesome-project",
  "branch_name": "main"
}
'
{
  "status": "ready",
  "progress": 100,
  "message": "Parsing ready successfully",
  "project_id": "proj_abc123def456"
}
Retrieve parsing status using repository name and branch instead of project ID.

​
Use Cases

  • Check parsing status when you only have repository details
  • Query status before knowing the project ID
  • Verify if a specific repo + branch combination has been parsed
  • Monitor parsing for repositories with specific commit IDs

​
Request Body

FieldTypeRequiredDescription
repo_namestringrequiredThe name of your repository
branch_namestringoptional*Branch name to check
commit_idstringoptional*Specific commit ID to check
Either commit_id or branch_name should be provided. If both are given, commit_id takes precedence.

​
Response

FieldTypeDescription
statusstringCurrent parsing state: submitted, cloned, parsed, processing, inferring, ready, or error
project_idstringThe unique project identifier
progressnumberPercentage completion (0-100)
messagestringStatus description

​
Example Workflow

const response = await fetch('https://production-api.potpie.ai/api/v2/parsing-status', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    repo_name: 'my-awesome-app',
    branch_name: 'main'
  })
});

const status = await response.json();
console.log(`Status: ${status.status}, Progress: ${status.progress}%`);

​
Polling for Completion

import time

def wait_for_parsing_by_repo(repo_name: str, branch_name: str):
    while True:
        response = requests.post(
            'https://production-api.potpie.ai/api/v2/parsing-status',
            headers={'x-api-key': 'YOUR_API_KEY'},
            json={
                'repo_name': repo_name,
                'branch_name': branch_name
            }
        )

        status = response.json()
        print(f"Status: {status['status']} - {status['progress']}%")

        if status['status'] == 'ready':
            return status
        elif status['status'] == 'error':
            raise Exception(f"Parsing failed: {status.get('message')}")

        time.sleep(5)  # Check every 5 seconds

​
Comparison: By Repo vs By Project ID

FeatureBy Repo (POST)By Project ID (GET)
Required InfoRepo name + branch/commitProject ID
HTTP MethodPOSTGET
Use CaseInitial status checkOngoing monitoring
PerformanceSlightly slowerFaster

​
Best Practices

  • Cache the project_id once you receive it for future queries
  • Prefer the project ID endpoint (Get Parsing Status) once you have the project_id
  • Use exponential backoff when polling to reduce server load
  • Set reasonable timeouts for long-running parsing operations

Authorizations

​
x-api-key
string
header
required

API key authentication. Get your key from potpie settings page

Body

application/json
​
repo_name
string
required

Repository name to check status for

​
commit_id
string

Commit ID to check (optional)

​
branch_name
string

Branch name to check (used if commit_id not provided)

Response

Parsing status retrieved successfully

​
status
enum<string>
Available options:
submitted,
cloned,
parsed,
processing,
inferring,
ready,
error
​
progress
integer
Required range: 0 <= x <= 100
​
message
string
​
project_id
string