Skip to main content
GET
/
api
/
v2
/
parsing-status
/
{project_id}
Get Parsing Status
curl --request GET \
  --url https://production-api.potpie.ai/api/v2/parsing-status/{project_id} \
  --header 'x-api-key: <api-key>'
{
  "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 the x-api-key header.
x-api-key: YOUR_API_KEY
LocationFieldTypeRequiredDescription
Pathproject_idstringrequiredUnique identifier of the project (returned from Parse Directory endpoint)
Responsestatusstring-Current parsing state: submitted, cloned, parsed, processing, inferring, ready, or error
Responselatestboolean-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(
      `https://production-api.potpie.ai/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));

Error Responses

The endpoint requires a valid API key for authentication.
{
  "detail": "API key is required"
}
Causes:
  • Missing x-api-key header
  • Invalid or expired API key
  • API key doesn’t match any user account
Solution: Include a valid API key in the request header:
x-api-key: YOUR_API_KEY
The endpoint returns this error when the project doesn’t exist or you lack access permissions.
{
  "detail": "Project not found or access denied"
}
Causes:
  • The project_id doesn’t exist in the database
  • You are not the project owner
  • The project is not shared with your account
  • The project was deleted
Solution: Verify the project_id is correct and ensure you have appropriate access permissions.
The endpoint returns this error when unexpected exceptions occur during status retrieval.
{
  "detail": "Internal server error"
}
Causes:
  • Database connection failures
  • Unexpected data format issues
  • Service unavailability
Solution: Retry the request after a brief delay. If the issue persists, contact support with the project_id.

Troubleshooting

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
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
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:
StatusDescriptionTypical Duration
submittedParsing request queuedImmediate
clonedRepository cloned successfully10-30 seconds
parsedCode structure analyzed1-5 minutes
processingBuilding knowledge graph5-15 minutes
inferringGenerating knowledge graph inferences5-20 minutes
readyParsing complete and readyFinal state
errorParsing failedFinal state

Authorizations

x-api-key
string
header
required

API key authentication. Get your key from potpie settings page

Path Parameters

project_id
string
required

The unique project identifier returned from the parse endpoint

Response

Parsing status retrieved successfully

status
enum<string>

Current parsing status

Available options:
submitted,
cloned,
parsed,
processing,
inferring,
ready,
error
latest
boolean

Whether the parsed commit matches the latest commit on the branch