What is the endpoint for [T012]DOCX translation status query?

The [T012]DOCX translation status query endpoint is POST https://connect.patsnap.com/docx-translation/api/v1/jobs/status.

Where can I find the OpenAPI schema for [T012]DOCX translation status query?

The OpenAPI schema is available at /openapi.json#/paths/~1docx-translation~1api~1v1~1jobs~1status/post. You can also browse the full specification at /openapi.json.

[T012]DOCX translation status query

Q: What data can [T012]DOCX translation status query return?

[T012]DOCX translation status query Look up a job once by `job_id` in the JSON body and return immediately (no polling). Callers poll this endpoint after an asynchronous submit. The first completed lookup is `ready` (billing header carries the actual amount); later lookups of the same successful job are `delivered` (not billed; `download_url` remains available). Pending or failed queries return billing header `0.000000`. See the Response Schema and Success Response Example on this page for the full structure.

post

https://connect.patsnap.com/docx-translation/api/v1/jobs/status

Try in Sandbox

Look up a job once by `job_id` in the JSON body and return immediately (no polling). Callers poll this endpoint after an asynchronous submit. The first completed lookup is `ready` (billing header carries the actual amount); later lookups of the same successful job are `delivered` (not billed; `download_url` remains available). Pending or failed queries return billing header `0.000000`.

Fixed path; `job_id` lives only in the JSON body. This endpoint does not download the file; after `ready`, open `download_url` directly.

Request Parameters

List of parameters supported by this API endpoint

Name	Type	Example	Description
`job_id` Required	`string`	`dcaf91fc699e`	Job identifier returned by `POST /docx-translation/api/v1/translations`, length 1-64. The generated value is 12 hexadecimal characters. Example: `dcaf91fc699e`.

{
  "job_id": "dcaf91fc699e"
}

Response Schema

Structure of the API response data

Field Name	Type	Example	Description
`error` Required	`string`	`upstream translation call failed after retries`	Exception string when `failed`; `null` for `queued` / `working` / `ready` / `delivered`. Example: `null` (not failed) or `"upstream translation call failed after retries"` (failed).
`job_id` Required	`string`	`dcaf91fc699e`	Job identifier, 12 hexadecimal characters. Example: `dcaf91fc699e`.
`status` Required	`string`	`ready`	Job status: `queued` accepted / `working` in progress / `ready` first completed result (billed) / `delivered` later lookup (not billed, still downloadable) / `failed` (see `error`). A synchronous submit always returns `ready`/`failed` (it is marked `billed` immediately and is never remapped to `delivered`). An asynchronous submit is usually `queued`, or `working` if the worker already started. `delivered` appears only on `POST /docx-translation/api/v1/jobs/status`. Example: `ready`.
`glossary`	`object`	{ "task": { "sha256": "9d5ed678fe57bcca610140957afab571f1283b3d0f7c6d8e9a0b1c2d3e4f5061", "filename": "task-glossary.json", "term_count": 2 }, "global": { "sha256": "5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e", "filename": "customer-glossary.json", "term_count": 2 }, "acceptance": { "passed": true, "report_path": "/reports/glossary-acceptance.json", "missing_terms": 0, "html_report_path": "/reports/glossary-acceptance.html", "markdown_report_path": "/reports/glossary-acceptance.md" } }	Customer glossary summary used by this job; null when no glossary was provided.
`job_type`	`string`	`translation`	Job type; translation for this submission endpoint.
`progress` Required	`string`	`100/100`	Progress as `current/100` percent string. Updates during `queued`/`working`; `ready`/`delivered` → `100/100`; `failed` → `0/100`.
`revision`	`object`	`{ "status": "completed", "changes": 12, "summary": "Patent-quality review completed.", "warnings": [], "reviewed_units": 128, "review_complete": true, "unreviewed_units": 0, "requested_changes": 12, "failed_review_batches": 0 }`	Automatic review result; null when disabled or unavailable.
`direction` Required	`string`	`zh-en`	Display form of the translation direction: zh-en for this Chinese-to-English public contract.
`provenance`	`object`	{ "summary": { "proven": 1, "term_pairs": 1, "needs_review": 0, "matched_families": 1 }, "direction": "zh2en", "term_pairs": [ { "terms": { "en": "processor", "id": 1, "zh": "处理器" }, "example": { "source": { "pn": "CN1234567A", "segment": "所述处理器执行指令。" }, "target": { "pn": "US1234567A", "segment": "The processor executes instructions." } }, "message": "Patent-family evidence found.", "origins": [ "translation" ], "segment": { "en": "The processor executes instructions.", "zh": "所述处理器执行指令。" }, "review_issue": { "code": "TERM_CONSISTENCY", "message": "Confirm terminology consistency." }, "display_status": "proven", "matched_families": { "items": [ { "source_pns": [ "CN1234567A" ], "target_pns": [ "US1234567A" ] } ], "total": 1 }, "provenance_status": "proven", "review_issue_count": 1 } ], "schema_version": "4.1", "document_version": "translated" }	Patent terminology provenance result; null when disabled or unavailable.
`download_url` Required	`string`	`https://translation-gpt-docx-stage.cos.ap-beijing.myqcloud.com/results/output/20241127_dcaf91fc699e_patent.en.docx?sign=...`	Signed URL for the final DOCX: reviewed output when review is enabled, otherwise ordinary translation. Available only at ready/delivered; empty if unavailable, COS is disabled or publication fails.
`source_chars` Required	`integer`	`17528`	Total source-text character count (sum of source text length across all translation units). Actual value when `ready` / `delivered`; `0` when `queued` / `working` / `failed`. The billing header equals `source_chars / 1e6` unless the 0.001 CNY floor applies, in which case the header is larger. Example: `17528` (billing header `0.017528`).
`auto_revision`	`boolean`	-	Effective automatic review switch after applying deployment configuration. The request parameter is named enable_revision.
`billing_amount` Required	`string`	`0.017528`	Billable amount in millions of source characters as a six-decimal string, equal to this response's `X-Openapi-Amount` header. Actual amount on synchronous `ready` and the first asynchronous `ready`; `0.000000` when `delivered` / `failed` / `queued` / `working` / async submit. Example: `0.017528` (17528 characters). Usage is returned in equivalent millions of source characters, not CNY. Ordinary translation uses a 1.0 factor; effective automatic review uses 1.5 (translation 1.0 + review 0.5). If `revision.review_complete=false`, the review component is waived and only the 1.0 translation factor applies. For 17528 source characters: ordinary translation `0.017528`, complete review `0.026292`. Minimum charge and base rate are deployment-configured; sync/async billing timing is unchanged.
`output_filename`	`string`	`patent_translation.en.docx`	Translated filename returned only when internal `output_mode=base64\|both` and `ready`. Example: `patent_translation.en.docx`.
`progress_detail`	`object`	`{ "phase": "translation", "total": 100, "current": 75, "message": "Translating document", "provenance": { "searched_terms": 12, "matched_families": 3 }, "phase_total": 4, "phase_current": 3 }`	Detailed progress; null when unavailable.
`provenance_mode`	`string`	`standard`	Provenance search intensity: fast prioritizes latency, standard balances latency and recall, full prioritizes recall (default). Has no effect when provenance is disabled.
`output_size_bytes`	`integer`	`245760`	Translated file size in bytes returned only when internal `output_mode=base64\|both` and `ready`. Example: `245760`.
`comparison_html_url`	`string`	`https://files.example.com/results/patent.comparison.html?sign=...`	Comparison HTML report URL, available for terminal results after successful publication; otherwise empty.
`file_content_base64`	`string`	`UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...`	Returned only when internal `output_mode=base64\|both` and `ready`; omitted in default public `url` mode. Example: `UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...`.
`output_content_type`	`string`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	MIME type returned only when internal `output_mode=base64\|both` and `ready`; always DOCX OOXML. Example: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`.
`revision_download_url`	`string`	`https://files.example.com/results/patent.revised.en.docx?sign=...`	Reviewed DOCX URL, available after completion and successful upload; otherwise empty.
`global_glossary_loaded`	`boolean`	-	Whether a user global glossary snapshot was loaded.
`translated_download_url`	`string`	`https://files.example.com/results/patent.translated.en.docx?sign=...`	Ordinary translated DOCX URL. With review enabled it may become available before the final result after upload. Empty if unavailable.
`task_glossary_term_count`	`integer`	`2`	Task glossary entry count; 0 if absent.
`comparison_html_diagnostic`	`object`	`{ "uploaded": true, "generated": true }`	Comparison report generation/upload diagnostics; null if unavailable. May include generation/upload status and failure reasons.
`global_glossary_term_count`	`integer`	-	Total entries in the loaded global glossary; 0 if none.
`global_glossary_version_id`	`string`	`global-20261021-001`	Loaded global glossary version, or null if none.
`global_glossary_canonical_sha256`	`string`	`5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e`	SHA-256 of the canonical global glossary, or null if none.

Success Response Example

Example of a successful API response

JSON

{
  "error": "upstream translation call failed after retries",
  "job_id": "dcaf91fc699e",
  "status": true,
  "glossary": {
    "task": {
      "sha256": "9d5ed678fe57bcca610140957afab571f1283b3d0f7c6d8e9a0b1c2d3e4f5061",
      "filename": "task-glossary.json",
      "term_count": 2
    },
    "global": {
      "sha256": "5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e",
      "filename": "customer-glossary.json",
      "term_count": 2
    },
    "acceptance": {
      "passed": true,
      "report_path": "/reports/glossary-acceptance.json",
      "missing_terms": 0,
      "html_report_path": "/reports/glossary-acceptance.html",
      "markdown_report_path": "/reports/glossary-acceptance.md"
    }
  },
  "job_type": "translation",
  "progress": "100/100",
  "revision": {
    "status": "completed",
    "changes": 12,
    "summary": "Patent-quality review completed.",
    "warnings": [],
    "reviewed_units": 128,
    "review_complete": true,
    "unreviewed_units": 0,
    "requested_changes": 12,
    "failed_review_batches": 0
  },
  "direction": "zh-en",
  "error_code": 0,
  "provenance": {
    "summary": {
      "proven": 1,
      "term_pairs": 1,
      "needs_review": 0,
      "matched_families": 1
    },
    "direction": "zh2en",
    "term_pairs": [
      {
        "terms": {
          "en": "processor",
          "id": 1,
          "zh": "处理器"
        },
        "example": {
          "source": {
            "pn": "CN1234567A",
            "segment": "所述处理器执行指令。"
          },
          "target": {
            "pn": "US1234567A",
            "segment": "The processor executes instructions."
          }
        },
        "message": "Patent-family evidence found.",
        "origins": [
          "translation"
        ],
        "segment": {
          "en": "The processor executes instructions.",
          "zh": "所述处理器执行指令。"
        },
        "review_issue": {
          "code": "TERM_CONSISTENCY",
          "message": "Confirm terminology consistency."
        },
        "display_status": "proven",
        "matched_families": {
          "items": [
            {
              "source_pns": [
                "CN1234567A"
              ],
              "target_pns": [
                "US1234567A"
              ]
            }
          ],
          "total": 1
        },
        "provenance_status": "proven",
        "review_issue_count": 1
      }
    ],
    "schema_version": "4.1",
    "document_version": "translated"
  },
  "download_url": "https://translation-gpt-docx-stage.cos.ap-beijing.myqcloud.com/results/output/20241127_dcaf91fc699e_patent.en.docx?sign=...",
  "source_chars": 17528,
  "auto_revision": false,
  "billing_amount": "0.017528",
  "output_filename": "patent_translation.en.docx",
  "progress_detail": {
    "phase": "translation",
    "total": 100,
    "current": 75,
    "message": "Translating document",
    "provenance": {
      "searched_terms": 12,
      "matched_families": 3
    },
    "phase_total": 4,
    "phase_current": 3
  },
  "provenance_mode": "standard",
  "output_size_bytes": 245760,
  "comparison_html_url": "https://files.example.com/results/patent.comparison.html?sign=...",
  "file_content_base64": "UEsDBBQABgAIAAAAIQCy0sNYxQEAACoHAAAL...",
  "output_content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "revision_download_url": "https://files.example.com/results/patent.revised.en.docx?sign=...",
  "global_glossary_loaded": false,
  "translated_download_url": "https://files.example.com/results/patent.translated.en.docx?sign=...",
  "task_glossary_term_count": 2,
  "comparison_html_diagnostic": {
    "uploaded": true,
    "generated": true
  },
  "global_glossary_term_count": 0,
  "global_glossary_version_id": "global-20261021-001",
  "global_glossary_canonical_sha256": "5f70bf18a08660b1f9c9ab08c675f3ab98aee3f55e8c15d36eaf9b4a7d8a1c2e"
}

Error Codes

List of possible error codes returned by this endpoint

Business Errors

Error Code	Description
`68300004`	Invalid parameter!
`68300005`	Search api failure!
`68300006`	Analytic basic access error!
`68300007`	Bad request!
`68300008`	Service error, please try again later!
`68300010`	The file does not comply with upload specifications!

Platform Errors

Error Code	Description
`67200001`	API call exceeds the total limit set by the platform!
`67200002`	Quota exceeds the limit!
`67200003`	Access token expired or authentication error!
`67200004`	No permission or API package quota has exceeded the limit!
`67200005`	Insufficient balance, call failed!
`67200006`	This client has expired and call failed!
`67200007`	Exceeded the call limit, call failed!

HTTP Status Codes

Status Code	Description
`0`	Success
`404`	Job not found
`422`	Missing `job_id`, or `job_id` is empty / longer than 64 characters. This endpoint uses FastAPI's default body validation, so `detail` is an array of error objects, not a string.