Skip to content

Reading project status

There's no single project.status field. Instead GET /project/{id} returns an elements object that groups the project's items (and files) by their current state, plus an elementStatuses array listing which states currently occur:

{
  "elementStatuses": ["in-progress", "finished"],
  "elements": {
    "in-progress": { "items": [99, 100] },
    "finished":    { "items": [98] }
  }
}

So "is it done?" becomes "are all the items in finished?". Count items (and files) across every group, count the ones in finished, compare.

Two things to keep in mind about the shape:

  • A group may have only items and no files key. Don't assume both are there.
  • finished is the terminal success state; error is the terminal failure.

The full set of item statuses: default, new, in-progress, feedback, approved, imported, rejected, finished, error, trash.

ProjectStatus collapses all of that into one of four values:

use Eurotext\ProjectStatus;

$status = ProjectStatus::fromProject($client->getProject($projectId));

match ($status) {
    ProjectStatus::PENDING     => // nothing counted yet — just submitted
    ProjectStatus::IN_PROGRESS => // some finished, some not — keep polling
    ProjectStatus::DELIVERED   => // everything in finished — go fetch results
    ProjectStatus::FAILED      => // at least one item errored — investigate
};

How each state is decided

  • pending — no items in any group.
  • delivered — finished count equals total.
  • failed — not all finished, and the error group is non-empty.
  • in_progress — anything else.

Delivered is checked before failed on purpose: if every item reached finished, treat the project as done even if an error bucket lingers from an earlier retry.

Partial delivery

Items finish independently, so you'll often see a project sitting in in_progress with some items already in finished. You can fetch and write back those finished items early instead of waiting for the whole project — just track which item ids you've already imported so you don't write the same one twice (see 12-idempotency.md). If you'd rather keep it simple, wait for delivered and fetch everything at once.

Polling vs. webhook

You can poll GET /project/{id} on a schedule, or register a webhook url when you create the project and let Eurotext notify you. Both are covered in 11-webhook-and-polling.md.