API docs
Book a demo

Content Enrichment API / Text Generation

Get text generation status

Page

POST /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.

Example request

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 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: Poll a run by its UUID (still in progress)
{
  "RunID": "0192fb50-8bb2-7abc-8def-112233445566"
}
Example request: Poll a run by its UUID (finished)
{
  "RunID": "0192fb50-8bb2-7abc-8def-112233445566"
}
Example request: Poll a run by its UUID (failed)
{
  "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

Body

application/json 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.

    8 fields
    • 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.

      4 fields
      • 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 response: A run still in progress
{
  "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 response: A finished run
{
  "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 response: A failed run
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: RunID not provided
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed",
    "Fields": [
      {
        "Field": "RunID",
        "Message": "RunID is required"
      }
    ]
  }
}
Example response: RunID is not a valid UUID
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid RunID format"
  }
}
Example response: Malformed request body
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Invalid API key
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Missing required scope
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.authoring:read"
  }
}
Example response: Project access required
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Text-generation run not found
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Limit exceeded
{
  "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

Body

application/json object ErrorResponse

Standard v2 error response wrapper.

  • Error object ErrorDetail required

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

    3 fields
    • 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.

      4 fields
      • 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
        {
          "Max": 100
        }
Example response: Internal server error
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to load text-generation run"
  }
}