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`	Analysis is not permitted. Either the file is a telecom, automotive, or kernel-dump log and your account doesn’t have the matching capability, or your account’s access period is closed, which restricts every file. Read the message to tell them apart. 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.

A file that finished with nothing in it

A file can reach COMPLETED and still have no results, because there was nothing in it to analyze. That is not a failure, and the status stays COMPLETED so your polling loop is unaffected. When it happens the response carries two extra fields:

Field	Meaning
`content_outcome: "empty"`	The file had no content.
`content_outcome: "unreadable"`	There was content, but it could not be read into anything analyzable.
`content_outcome: "none_analyzable"`	The file was read fine and held nothing analyzable, often a capture over a quiet period.

content_detail carries the same answer as a sentence you can show a user. Both fields are absent on an ordinary analysis, so treat their presence as the signal.

Two limits on that signal. It is not a terminal marker: one of the three is settled part way through, so you can see it on a file that is still ANALYZING. Keep using status to decide when to stop polling. And not every file answers yet, so an absent field is not a claim that the file had content: network captures, traces, kernel dumps, baseband captures and multi-file bundles carry no outcome, and neither does anything processed before this shipped.

If you show results in your own UI, read content_outcome before rendering an empty state. Without it a finished file with no findings looks the same as one the platform failed to process.

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.
A COMPLETED file may carry content_outcome (above). COMPLETED is still terminal; stop polling and read that field before deciding what to show. Don’t stop on the field’s presence alone, though: it can appear while the file is still ANALYZING.
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.