Analysis lifecycle & polling

Analysis is asynchronous. After you upload a file you poll its status until it reaches a terminal state. This page describes that state machine.

Polling

curl "https://api.logcat.ai/api/v1/files/<fileId>" \
  -H "Authorization: API_KEY $LOGCAT_API_KEY"

The response carries a single status field.

The state enum

The first status you’ll see after a successful upload is INDEXING.

Status	Meaning
`INDEXING`	The file is being prepared for analysis and search.
`ANALYZING`	AI analysis is running across subsystems.
`VISUALIZING`	Analysis is done; the dashboard is being generated.
`COMPLETED`	Ready. Results and the dashboard are fully available.
`FAILED`	Processing failed. May be retryable (see below).
`PLAN_RESTRICTED`	The file is a telecom, automotive, or kernel-dump log and your account doesn’t have the matching capability. See Why was I limited?.

Wait for `COMPLETED`

COMPLETED is the only ready signal. At VISUALIZING the results aren’t finished yet, so keep polling. Fetching results before COMPLETED returns an incomplete dashboard.

Handling `FAILED`

On FAILED, the response always includes a can_retry flag:

can_retry: true: the failure was transient and the platform may recover it on its own. Keep polling, the file can still move on to COMPLETED. Re-submitting also works.
can_retry: false: retries are exhausted. The failure is terminal, and re-uploading is the only path.

Polling guidance

Poll on an interval (every few seconds is fine), but respect the rate limits.
Stop when status is COMPLETED, PLAN_RESTRICTED, or FAILED with can_retry: false. A FAILED with can_retry: true is not terminal, so don’t give up on it.
Prefer webhooks if you’d rather be notified than poll. See Webhooks.

Next steps

API quickstart: a full upload → poll → dashboard → search loop.
Webhooks: get a callback on completion instead of polling.