---
title: "POST /v2/costformation/definitions/async"
method: POST
path: "/v2/costformation/definitions/async"
tags: ["costformation"]
---

# POST /v2/costformation/definitions/async

`POST /v2/costformation/definitions/async`

Submit an asynchronous CostFormation definition publish job. Returns a job ID, initial status of `pending`, and a `poll_url` to check progress. Use the [Get a publish job](https://docs.cloudzero.com/reference/getcostformationpublishjob) endpoint to poll for completion.

## Headers

- `cloudzero-idempotency-key` string
- `cloudzero-test-key` string

## Request body

- CostformationAsyncPublishRequest
  - `definitions` object, required
    - `yaml` string, required — The CostFormation definition content in YAML format.
  - `validate_only` boolean — If true, validates the definition without creating a publish job.
  - `save_draft_only` boolean — If true, saves the definition as a draft without publishing.
  - `compression` string, nullable — Optional compression format applied to the definition payload.

## Response `200`

Successful Operation

- CostformationPublishJob — Response returned when a publish job is created.
  - `job_id` string — Unique identifier for the publish job.
  - `status` string — Current status of the publish job. One of: `pending`, `in_progress`, `completed`, `failed`, `superseded`, `cancelled`.
  - `poll_url` string — URL path to poll for job status updates.

## Other responses

- `400` — Bad Request Error
- `403` — Forbidden

---

[API](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources.md) · [All operations](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cloudzero/cloudzero-api-v2-resources/revisions/fd805a0e75e5/schema)