# get_publish_status

Source: https://modulify.ai/docs/api/publishing/get-publish-status

Reads the state of a site's most recent publish, plus its public subdomain and custom domains.

- Title: Check a publish
- Scope: `sites:read`
- Access: Read only
- Endpoint: `POST /v1/get_publish_status`

`running:true` means the publish is still going, so poll every few seconds until it is false, then read `status`. Only `ready` means the new build is live. `failed` and `cancelled` are the other two endings, with the reason in `error`, and anything else (`provisioning`, `machine-created`, `machine-started`, `machine-healthy`, `deploying` or `cancelling`) is a step still in flight.

The answer also carries the most recent publish's `deploymentId` and the site's `subdomain`. A site that has never been published answers with `status` null and `running` false.

`customDomain` is the site's primary domain: the first custom domain, in the order they were added, that is connected, else the first connected www companion. It is null while none is connected or while the custom domains are [paused](https://modulify.ai/docs/publish/custom-domains#when-your-plan-ends).

`domains` lists every custom domain with its `_id`, its www companion, whether each hostname is connected and its DNS records. `domainsPaused` is true while the domains are paused because the workspace has no paid plan any more, and none of them serves the site until it is on a paid plan again. See [Publish a site](https://modulify.ai/docs/publish/publish-a-site).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/get_publish_status`, sending the inputs below as a JSON object. The token needs the `sites:read` scope.

It only reads and changes nothing, so retrying it is safe.

```bash
curl -X POST https://api.modulify.ai/v1/get_publish_status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}'
```

Over MCP, the same method is the [get_publish_status tool](https://modulify.ai/docs/mcp/publishing/get-publish-status).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.