> ## Documentation Index > Fetch the complete documentation index at: https://docs.valendata.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a skill improvement > Poll an improvement until it is done or has failed. See its mode, its result, each field's rows before and after, and which fields were added, merged, or need an answer. The account that started it and anyone who can edit the Skill (its owner or a workspace editor) can poll it; anyone else gets 404. ## OpenAPI ````yaml GET /v1/skill-improvements/{improvement_id} openapi: 3.0.3 info: title: Valendata REST API version: 1.0.0 description: >- Trigger Skills, manage Workflows, retrieve Runs, and stream structured results from any language using JSON over HTTPS. servers: - url: https://api.valendata.com description: Production security: - ApiKeyAuth: [] tags: - name: Skills description: Execute and inspect published Skills. - name: Workflows description: Trigger multi-step Workflows and list them. - name: Runs description: Start async Skill runs and read Skill and Workflow run results. - name: Skill creation description: Create a Skill from a plain-language task. - name: Skill improvement description: >- Fix a Skill, add fields to it or re-learn its detail steps, poll the result, and read its change history. - name: Versions description: List, diff, restore, and pin a Skill's recipe versions. - name: Webhooks description: Signed delivery of finished async runs. paths: /v1/skill-improvements/{improvement_id}: get: tags: - Skill improvement summary: Get a Skill improvement description: >- Where an improvement is: `queued`, `working`, `validating`, `done` (`result` and `improved` say whether the new version is live; `changes` shows each field before → after; `details` shows new, merged and unclear fields) or `failed` (`error`). The account that started it and anyone who can edit the Skill (its owner or a workspace editor) can poll it; anyone else gets 404. operationId: getSkillImprovement parameters: - name: improvement_id in: path required: true schema: type: string example: imp_3f9a1c2b7d4e5f60 responses: '200': description: The improvement's current state. content: application/json: schema: $ref: '#/components/schemas/SkillImprovementStatus' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' security: - ApiKeyAuth: [] components: schemas: SkillImprovementStatus: type: object properties: improvement_id: type: string example: imp_3f9a1c2b7d4e5f60 status: type: string enum: - queued - working - validating - done - failed status_url: type: string example: /v1/skill-improvements/imp_3f9a1c2b7d4e5f60 skill_id: type: string slug: type: string nullable: true mode: type: string enum: - fix - add_fields - relearn_details description: The mode it ran in. source: type: string enum: - api - mcp - assistant - web - brain - imported description: >- Where it was started: `api`, `mcp`, `assistant` (Igris), `web` (the web app), `brain` (the workflow Brain chat), or `imported` (a past Refine or Re-learn from before improvements were unified). started_by_name: type: string nullable: true description: The name of the person who started it. feedback: type: string nullable: true strategy: type: string nullable: true enum: - fields - rerecord description: '`fields`: relearn where the fields live. `rerecord`: redo the steps.' target_fields: type: array items: type: string diagnosis: allOf: - $ref: '#/components/schemas/Diagnosis' nullable: true description: The diagnosis it started from. diagnosis_after: allOf: - $ref: '#/components/schemas/Diagnosis' nullable: true description: The check run's diagnosis, when fields are still missing. fields_before: type: object additionalProperties: type: object properties: filled: type: integer total: type: integer rate: type: number fields_after: type: object additionalProperties: type: object properties: filled: type: integer total: type: integer rate: type: number changes: type: array items: type: object properties: field: type: string before: type: string example: 0/5 after: type: string example: 5/5 improved: type: boolean improved: type: boolean nullable: true description: >- True: the new version is live. False: kept as a candidate, the old recipe restored. result: type: string enum: - running - improved - kept_old - no_change - failed - applied description: >- Short verdict. `running`: not finished. `improved`: the new version is live. `kept_old`: not better, so the old version stayed live. `no_change`: nothing needed changing. `failed`: see `error`. `applied`: imported from the old Refine history, applied without a check run. imported: type: boolean description: True for a past Refine or Re-learn entry imported into this history. details: type: object nullable: true description: What the engine decided. properties: new_fields: type: array items: type: string description: Fields added (`add_fields`). merged: type: array description: >- Requested fields that were re-worded duplicates of existing ones, merged into them. items: type: object properties: proposed: type: string into: type: string note: type: string ambiguous: type: array description: >- Requested fields that were unclear and were not learned. Answer `question` and send a new request. items: type: object properties: proposed: type: string candidates: type: array items: type: string question: type: string diff_summary: type: string nullable: true description: One line on what changed in the recipe. engine_note: type: string nullable: true description: Any extra note from the engine. recipe_version_before: type: integer nullable: true recipe_version: type: integer nullable: true description: The live version when it ended. candidate_version: type: integer nullable: true description: The version kept but not made live. outcome: type: string nullable: true error: type: string nullable: true credits_charged: type: integer created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true finished_at: type: string format: date-time nullable: true idempotent_replay: type: boolean Diagnosis: type: object description: >- Why a run, validation or creation came back short, and hints that could fix it with `POST /v1/skills/{slug}/improve`. properties: rows: type: integer missing_fields: type: array items: type: string description: Fields fewer than half the rows came back with. per_field: type: object additionalProperties: $ref: '#/components/schemas/FieldDiagnosis' triage_kind: type: string nullable: true example: missing_fields what_we_tried: type: array items: type: string suggested_hint_examples: type: array items: type: string error: type: string nullable: true summary: type: string example: 'phone: found on 0/5 rows — tried the result cards' Error: type: object properties: detail: oneOf: - type: string - type: object additionalProperties: true description: >- Error message. Usually a plain string; may be a structured object for some errors. example: detail: Invalid or expired API key FieldDiagnosis: type: object properties: filled: type: string example: 0/5 description: Rows that had the field. filled_count: type: integer total: type: integer where_tried: type: array items: type: string example: - the result cards - each row's details page evidence: type: string example: blank on all 5 rows responses: Unauthorized: description: >- Unauthorized. The Authorization header is missing, malformed, or the credential is invalid or expired. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found in your Workspace. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: vd_sk_... description: >- API key with the `vd_sk_` prefix. Create keys from Settings, API Keys in the dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.