> ## Documentation Index > Fetch the complete documentation index at: https://docs.perfai.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get task status > Returns the current state of any task on this API — a registration, a security test, or a Vision Agent run. Every action that starts work returns a taskId; poll this URL until state is COMPLETED, FAILED, CANCELLED or INTERRUPTED. ## OpenAPI ````yaml /api-reference/openapi.yaml get /tasks/{taskId} openapi: 3.1.1 info: title: Perfai Security API version: 1.1.0 description: > Partner-facing REST API for automating Perfai security testing: register apps, trigger security tests and vision (browser-automation) runs, poll run status, and retrieve vulnerability findings. All endpoints are JWT-authenticated and scoped to the caller's organization; cross-tenant access returns 404 (never 403) to prevent enumeration. Errors follow RFC 9457 Problem Details. servers: - url: https://api.perfai.ai/v1 description: Perfai cloud - url: https://api.{customerDomain}/v1 description: On-premise deployment variables: customerDomain: default: example.com security: - bearerAuth: [] tags: - name: Apps description: App catalog — list, register, and poll registration. - name: Security Agent description: Trigger security tests and poll their lifecycle. - name: Vision Agent description: >- Trigger vision (browser-automation) runs and poll their lifecycle. Always browserless. - name: Vulnerabilities description: Retrieve security findings. - name: Reports description: List an app's security reports and download them as PDF. - name: Tasks description: Poll any asynchronous operation started by this API. paths: /tasks/{taskId}: get: tags: - Tasks summary: Get task status description: > Returns the current state of any task on this API — a registration, a security test, or a Vision Agent run. Every action that starts work returns a taskId; poll this URL until state is COMPLETED, FAILED, CANCELLED or INTERRUPTED. operationId: getTask parameters: - $ref: '#/components/parameters/TaskId' responses: '200': description: Current task state. content: application/json: schema: $ref: '#/components/schemas/Task' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: TaskId: name: taskId in: path required: true schema: type: string description: > Task identifier returned by register, run-security-agent or run-vision-agent (for example task_wf_683def5678901abcd1234abc). Opaque — pass it back verbatim, do not parse it. schemas: Task: type: object required: - taskId - type - appId - state - createdAt - updatedAt - result properties: taskId: type: string description: Opaque task identifier. Pass it back verbatim; do not parse it. example: task_wf_683def5678901abcd1234abc type: type: string description: What kind of work this task represents. enum: - security-agent - vision-agent - registration example: security-agent appId: type: string example: 683abc1234567890abcdef12 state: $ref: '#/components/schemas/TaskState' createdAt: type: string format: date-time nullable: true updatedAt: type: string format: date-time nullable: true description: Null if the task has not changed since it was created. result: description: | Type-specific detail; the shape follows `type`. oneOf: - $ref: '#/components/schemas/SecurityTestResult' - $ref: '#/components/schemas/VisionRunResult' - $ref: '#/components/schemas/RegistrationResult' TaskState: type: string description: > Shared lifecycle vocabulary for every task. AWAITING_INPUT means the work has stopped and is waiting for something only you can supply — in practice, test-account credentials for an app the platform could not sign itself up to. Answer it with POST /v1/apps/{appId}/account-setup, after which the task returns to RUNNING. Treat it as non-terminal but do not wait on it: nothing will change until you act. INTERRUPTED means the work was destroyed before reporting an outcome — deliberately not folded into COMPLETED or FAILED, because "completed with zero findings" and "we do not know what it would have found" are different answers. enum: - QUEUED - RUNNING - AWAITING_INPUT - COMPLETED - FAILED - CANCELLED - INTERRUPTED SecurityTestResult: type: object properties: runNumber: type: integer description: Sequence number of this test among the app's security tests. example: 7 vulnerabilitiesUrl: type: string description: > Where to read the findings. Present only once state is COMPLETED — a FAILED or INTERRUPTED test has no trustworthy findings to offer. example: >- https://api.perfai.ai/v1/apps/683abc1234567890abcdef12/vulnerabilities intervention: $ref: '#/components/schemas/Intervention' VisionRunResult: type: object properties: operation: type: string description: The vision operation this run performed. example: map RegistrationResult: type: object properties: registrationStatus: type: string description: Registration lifecycle status of the app. enum: - PENDING - IN_PROGRESS - COMPLETED - FAILED - CANCELLED example: IN_PROGRESS intervention: $ref: '#/components/schemas/Intervention' Problem: type: object description: RFC 9457 Problem Details. properties: type: type: string description: Error type URI, e.g. https://perfai.ai/errors/app-already-registered title: type: string additionalProperties: true Intervention: type: object description: > What the platform is waiting for while a task is AWAITING_INPUT. Most pauses are cleared by changing something in your own application — granting a permission, clearing a CAPTCHA, or fixing whatever made a step fail repeatedly. Supplying test-account credentials is the one case this API can answer directly, via POST /v1/apps/{appId}/account-setup. For every other type, resolving the pause is a console action; this endpoint reports it so you know what to fix. required: - type - title - fields properties: type: type: string enum: - manual_credentials - otp_mfa - role_define - permission_fix - manual_account - generic_confirm example: generic_confirm title: type: string example: This step keeps failing and needs your input to continue reason: type: string description: Underlying failure that caused the pause, when one was recorded. fields: type: array description: > Values the platform would need to continue automatically. Often empty — most pauses need a change in your application rather than data from you. items: type: object required: - key - label - type - required properties: key: type: string example: username label: type: string example: Username / email type: type: string enum: - text - password - otp - select required: type: boolean options: type: array items: type: string expiresAt: type: string format: date-time nullable: true responses: Unauthorized: description: Missing or expired JWT. NotFound: description: Resource not found or belongs to a different tenant. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > JWT login token tied to your Perfai user (not a separate API key). Obtain it via POST /api/v1/auth/token with your username and password (use the returned id_token) — the same login the web console performs. Carries org, user, and role; short-lived. ````