# Get text generation status

Content Enrichment API / Text Generation

`POST https://api.ygo.ai/v2/project/content/getTextGenerationStatus`

Retrieve the status and progress of a text-generation run by its UUID. Use this to poll the asynchronous run started by generateText until its Status becomes 'complete' or 'failed'. A run that does not belong to the calling project returns 404.

Exact spec (OpenAPI 3.0, JSON): https://docs.ygo.ai/reference/getTextGenerationStatus.json

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/getTextGenerationStatus' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "RunID": "0192fb50-8bb2-7abc-8def-112233445566"
}'
```

## Authorization

`Authorization: Bearer <key>`

Project-scoped API key

## Headers

- `X-Project-ID` (string (uuid), **required**)

  Project UUID. Required for all project-scoped endpoints.

  Example: `$YGO_PROJECT_ID`

## Request body

Required.

### application/json

Schema: object, `GetTextGenerationStatusRequest`

Request body for fetching the status of a single text-generation run.

- `RunID` (string (uuid), **required**)

  UUID of the text-generation run to retrieve, as returned by generateText. The run must belong to the calling project.

  Example: `0192fb50-8bb2-7abc-8def-112233445566`

#### Example request: processing. Poll a run by its UUID (still in progress)

```json
{
  "RunID": "0192fb50-8bb2-7abc-8def-112233445566"
}
```

#### Example request: complete. Poll a run by its UUID (finished)

```json
{
  "RunID": "0192fb50-8bb2-7abc-8def-112233445566"
}
```

#### Example request: failed. Poll a run by its UUID (failed)

```json
{
  "RunID": "0192fb50-8bb2-7abc-8def-112233445566"
}
```

## Responses

### 200 OK

Text-generation run status retrieved successfully.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `GetTextGenerationStatusResponse`

Single-object response envelope wrapping the text-generation run status.

- `Data` (object, `TextGenerationStatus`, **required**)

  The status and progress of a text-generation run.

  - `ID` (string (uuid), **required**)

    Unique run UUID.

    Example: `0192fb50-8bb2-7abc-8def-112233445566`
  - `Status` (string, **required**)

    Run lifecycle status. A freshly created run is 'queued'; it transitions to 'processing' while running, then to 'complete' or 'failed'.

    Values: `queued`, `processing`, `complete`, `failed`

    Example: `processing`
  - `Progress` (object, `RunProgress`, **required**)

    Per-hotel progress counters for the run.

    - `Total` (integer, **required**)

      Total number of hotels in the run.

      Example: `5`
    - `Generated` (integer, **required**)

      Number of hotels for which text has been generated so far.

      Example: `2`
    - `Failed` (integer, **required**)

      Number of hotels that failed processing.

      Example: `0`
    - `Skipped` (integer, **required**)

      Number of hotels skipped because they needed no work.

      Example: `0`
  - `ErrorMessage` (string)

    Human-readable error message when the run has failed. Empty or omitted otherwise.

    Example: ``
  - `StartedAt` (string (date-time))

    Timestamp when the run started processing (RFC3339). Omitted until the run has started.

    Example: `2026-06-26T09:15:05Z`
  - `CompletedAt` (string (date-time))

    Timestamp when the run finished (RFC3339). Omitted until the run has finished.

    Example: `2026-06-26T09:18:42Z`
  - `CreatedAt` (string (date-time), **required**)

    Timestamp when the run record was created (RFC3339).

    Example: `2026-06-26T09:15:00Z`
  - `UpdatedAt` (string (date-time), **required**)

    Timestamp when the run record was last updated (RFC3339).

    Example: `2026-06-26T09:16:10Z`

##### Example: processing. A run still in progress

```json
{
  "Data": {
    "ID": "0192fb50-8bb2-7abc-8def-112233445566",
    "Status": "processing",
    "Progress": {
      "Total": 5,
      "Generated": 2,
      "Failed": 0,
      "Skipped": 0
    },
    "StartedAt": "2026-06-26T09:15:05Z",
    "CreatedAt": "2026-06-26T09:15:00Z",
    "UpdatedAt": "2026-06-26T09:16:10Z"
  }
}
```

##### Example: complete. A finished run

```json
{
  "Data": {
    "ID": "0192fb50-8bb2-7abc-8def-112233445566",
    "Status": "complete",
    "Progress": {
      "Total": 5,
      "Generated": 5,
      "Failed": 0,
      "Skipped": 0
    },
    "StartedAt": "2026-06-26T09:15:05Z",
    "CompletedAt": "2026-06-26T09:18:42Z",
    "CreatedAt": "2026-06-26T09:15:00Z",
    "UpdatedAt": "2026-06-26T09:18:42Z"
  }
}
```

##### Example: failed. A failed run

```json
{
  "Data": {
    "ID": "0192fb50-8bb2-7abc-8def-112233445566",
    "Status": "failed",
    "Progress": {
      "Total": 5,
      "Generated": 1,
      "Failed": 4,
      "Skipped": 0
    },
    "ErrorMessage": "Text generation failed for one or more hotels",
    "StartedAt": "2026-06-26T09:15:05Z",
    "CompletedAt": "2026-06-26T09:16:20Z",
    "CreatedAt": "2026-06-26T09:15:00Z",
    "UpdatedAt": "2026-06-26T09:16:20Z"
  }
}
```

### 400 Bad Request

Bad Request - Validation error or invalid request body.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `RunID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `RunID is required`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: missingRunID. RunID not provided

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "RunID",
        "Message": "RunID is required"
      }
    ]
  }
}
```

##### Example: invalidRunID. RunID is not a valid UUID

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid RunID format"
  }
}
```

##### Example: invalidBody. Malformed request body

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid request body"
  }
}
```

### 401 Unauthorized

Unauthorized - Invalid or missing API key.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `RunID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `RunID is required`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidKey. Invalid API key

```json
{
  "Error": {
    "Code": "UNAUTHORIZED",
    "Message": "Invalid API key"
  }
}
```

### 403 Forbidden

Forbidden - Valid API key but insufficient permissions for this operation. Also returned with code INSUFFICIENT_SCOPE when the API key does not carry the content.authoring:read permission this endpoint requires.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `RunID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `RunID is required`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: insufficientScope. Missing required scope

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.authoring:read"
  }
}
```

##### Example: noProjectAccess. Project access required

```json
{
  "Error": {
    "Code": "FORBIDDEN",
    "Message": "Project access required"
  }
}
```

### 404 Not Found

Not Found - The run does not exist or is not owned by the calling project.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `RunID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `RunID is required`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: runNotFound. Text-generation run not found

```json
{
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Text-generation run not found"
  }
}
```

### 429 Too Many Requests

Too Many Requests. The response includes a `Retry-After` header with the number of seconds to wait before retrying.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`
- `Retry-After` (integer)

  Number of seconds to wait before retrying the request. Present on 429 responses.

  Example: `30`

  Limits: min 1

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `RunID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `RunID is required`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: rateLimited. Limit exceeded

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
  }
}
```

### 500 Internal Server Error

Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Request validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation.

      Example: `RunID`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `RunID is required`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: internalError. Internal server error

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to load text-generation run"
  }
}
```
