Get Parsing Status
curl --request GET \
--url http://localhost:8001/api/v2/parsing-status/{project_id} \
--header 'x-api-key: <api-key>'import requests
url = "http://localhost:8001/api/v2/parsing-status/{project_id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('http://localhost:8001/api/v2/parsing-status/{project_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8001",
CURLOPT_URL => "http://localhost:8001/api/v2/parsing-status/{project_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:8001/api/v2/parsing-status/{project_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:8001/api/v2/parsing-status/{project_id}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8001/api/v2/parsing-status/{project_id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"status": "processing",
"latest": false
}Potpie API
Get Parsing Status
Check the parsing status of a specific project using its project ID. Returns the current status and whether the parsed commit matches the latest commit on the branch.
GET
/
api
/
v2
/
parsing-status
/
{project_id}
Get Parsing Status
curl --request GET \
--url http://localhost:8001/api/v2/parsing-status/{project_id} \
--header 'x-api-key: <api-key>'import requests
url = "http://localhost:8001/api/v2/parsing-status/{project_id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('http://localhost:8001/api/v2/parsing-status/{project_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8001",
CURLOPT_URL => "http://localhost:8001/api/v2/parsing-status/{project_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:8001/api/v2/parsing-status/{project_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:8001/api/v2/parsing-status/{project_id}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8001/api/v2/parsing-status/{project_id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"status": "processing",
"latest": false
}Check the current parsing status of a repository. Monitor whether parsing has completed and if the parsed version matches the latest commit on the branch.
Authentication
This endpoint requires API key authentication via thex-api-key header.
x-api-key: YOUR_API_KEY
Request & Response
Request & Response
| Location | Field | Type | Required | Description |
|---|---|---|---|---|
| Path | project_id | string | required | Unique identifier of the project (returned from Parse Directory endpoint) |
| Response | status | string | - | Current parsing state: submitted, cloned, parsed, processing, inferring, ready, or error |
| Response | latest | boolean | - | Whether the parsed commit matches the latest commit on the branch |
Complete Workflow
async function waitForParsingComplete(projectId: string): Promise<void> {
const maxAttempts = 60; // 10 minutes with 10s intervals
let attempts = 0;
while (attempts < maxAttempts) {
const response = await fetch(
`http://localhost:8001/api/v2/parsing-status/${projectId}`,
{
headers: {
'x-api-key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();
console.log(`Status: ${data.status}`);
console.log(`Is Latest: ${data.latest}`);
if (data.status === 'ready') {
console.log('Parsing ready successfully!');
return;
}
if (data.status === 'error') {
throw new Error('Parsing failed');
}
await new Promise(resolve => setTimeout(resolve, 10000)); // Wait 10s
attempts++;
}
throw new Error('Parsing timeout - took longer than expected');
}
// Usage
waitForParsingComplete('proj_456')
.then(() => console.log('Ready to use agents!'))
.catch(error => console.error(error));
import requests
import time
def get_parsing_status(project_id: str) -> dict:
"""Get the current parsing status for a project."""
response = requests.get(
f'http://localhost:8001/api/v2/parsing-status/{project_id}',
headers={'x-api-key': 'YOUR_API_KEY'}
)
return response.json()
def wait_for_parsing(project_id: str, timeout: int = 600):
"""
Wait for parsing to complete with timeout.
Args:
project_id: The project ID to monitor
timeout: Maximum time to wait in seconds (default 10 minutes)
"""
start_time = time.time()
while time.time() - start_time < timeout:
status_data = get_parsing_status(project_id)
print(f"Status: {status_data['status']}")
print(f"Is Latest: {status_data['latest']}")
print("-" * 50)
if status_data['status'] == 'ready':
return True
elif status_data['status'] == 'error':
raise Exception("Parsing failed")
time.sleep(10)
raise TimeoutError(f"Parsing did not complete within {timeout} seconds")
# Usage
try:
wait_for_parsing('proj_456')
print("Project is ready!")
except Exception as e:
print(f"Error: {e}")
# Simple status check
curl -X GET \
'http://localhost:8001/api/v2/parsing-status/proj_456' \
-H 'x-api-key: YOUR_API_KEY'
# Continuous monitoring with watch (Linux/Mac)
watch -n 10 'curl -s -X GET \
"http://localhost:8001/api/v2/parsing-status/proj_456" \
-H "x-api-key: YOUR_API_KEY" | jq'
Error Responses
401 Unauthorized
401 Unauthorized
The endpoint requires a valid API key for authentication.Causes:
{
"detail": "API key is required"
}
- Missing
x-api-keyheader - Invalid or expired API key
- API key doesn’t match any user account
x-api-key: YOUR_API_KEY
404 Not Found
404 Not Found
The endpoint returns this error when the project doesn’t exist or you lack access permissions.Causes:
{
"detail": "Project not found or access denied"
}
- The
project_iddoesn’t exist in the database - You are not the project owner
- The project is not shared with your account
- The project was deleted
project_id is correct and ensure you have appropriate access permissions.500 Internal Server Error
500 Internal Server Error
The endpoint returns this error when unexpected exceptions occur during status retrieval.Causes:
{
"detail": "Internal server error"
}
- Database connection failures
- Unexpected data format issues
- Service unavailability
project_id.Troubleshooting
Status stuck at 'submitted'
Status stuck at 'submitted'
Problem: Status remains at ‘submitted’ for an extended period.Solution:
- The parsing queue might be busy. Wait a few minutes and check again
- If it persists for more than 5 minutes, contact support with your project ID
- Very large repositories may take longer to begin processing
Status shows 'error'
Status shows 'error'
Problem: Parsing failed to complete.Solution:
- Verify the repository is accessible
- Check that the branch exists
- Ensure the repository structure is valid
- Consider that very large repositories may timeout
- Contact support if the issue persists
latest field is false
latest field is false
Problem: The
latest field shows false even though status is ready.Solution:- This indicates the branch has new commits since parsing
- Re-parse the repository to get the latest code analysis
- This is expected behavior for active branches with ongoing development
Status Phases
During parsing, you’ll see different status values corresponding to analysis stages:| Status | Description | Typical Duration |
|---|---|---|
submitted | Parsing request queued | Immediate |
cloned | Repository cloned successfully | 10-30 seconds |
parsed | Code structure analyzed | 1-5 minutes |
processing | Building knowledge graph | 5-15 minutes |
inferring | Generating knowledge graph inferences | 5-20 minutes |
ready | Parsing complete and ready | Final state |
error | Parsing failed | Final state |
Authorizations
API key authentication. Get your key from potpie settings page
Path Parameters
The unique project identifier returned from the parse endpoint
Was this page helpful?

