> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a task

> Retrieve an existing task in the workspace.



## OpenAPI

````yaml /schemas/2025-06-09.json get /v1/tasks/{taskId}
openapi: 3.1.0
info:
  title: Folk External API
  description: >-
    Folk's public REST API lets you manage workspaces, groups, contacts, and
    real-time triggers.
  version: '2025-06-09'
  contact:
    name: folk
    email: tech@folk.app
    url: https://folk.app
servers:
  - url: https://api.folk.app
    description: Folk's public API production base URL.
    x-internal: false
security: []
tags:
  - name: Companies
    description: Operations related to companies.
  - name: Deals
    description: Operations related to deals.
  - name: Groups
    description: Operations related to groups.
  - name: Group members
    description: Operations related to group members.
  - name: Group custom fields
    description: Operations related to group custom fields.
  - name: Interactions
    description: Operations related to interactions.
  - name: Notes
    description: Operations related to notes.
  - name: People
    description: Operations related to people.
  - name: Reminders
    description: Operations related to reminders.
  - name: Tasks
    description: Operations related to tasks.
  - name: Users
    description: Operations related to users.
  - name: Webhooks
    description: Operations related to webhooks.
paths:
  /v1/tasks/{taskId}:
    get:
      tags:
        - Tasks
      summary: Get a task
      description: Retrieve an existing task in the workspace.
      operationId: getTask
      parameters:
        - schema:
            type: string
            minLength: 40
            maxLength: 40
          required: true
          description: The ID of the task to get.
          name: taskId
          in: path
      responses:
        '200':
          description: The task that has been retrieved.
          links:
            updateTask:
              operationId: updateTask
              parameters:
                taskId: $response.body#/data/id
              description: >-
                This task id can be used as an input to the `PATCH
                /v1/tasks/:taskId` operation to update the task.
            deleteTask:
              operationId: deleteTask
              parameters:
                taskId: $response.body#/data/id
              description: >-
                This task id can be used as an input to the `DELETE
                /v1/tasks/:taskId` operation to delete the task.
            markAsDone:
              operationId: markAsDone
              parameters:
                taskId: $response.body#/data/id
              description: >-
                This task id can be used as an input to the `POST
                /v1/tasks/:taskId/mark-as-done` operation to mark the task as
                done.
            markAsTodo:
              operationId: markAsTodo
              parameters:
                taskId: $response.body#/data/id
              description: >-
                This task id can be used as an input to the `POST
                /v1/tasks/:taskId/mark-as-todo` operation to mark the task as to
                do.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TSK_Task'
                  deprecations:
                    type: array
                    items:
                      type: string
                    example:
                      - This field is deprecated
                required:
                  - data
              example:
                data:
                  id: tsk_91118b73-5a75-480b-b8e3-a33671c35cdc
                  title: Follow up with John Doe
                  description: Discuss the Q3 proposal.
                  entity:
                    id: per_55175e81-9a52-4ac3-930e-82792c23499b
                    entityType: person
                    fullName: John Doe
                  dueAt: '2025-07-17'
                  dueTime: '15:00'
                  completedAt: null
                  recurrenceFrequency: null
                  isPublic: true
                  assignedUsers:
                    - id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
                      fullName: John Doe
                      email: john.doe@example.com
                  createdBy:
                    id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
                    fullName: John Doe
                    email: john.doe@example.com
                  createdAt: '2025-07-17T09:00:00.000Z'
                  updatedAt: '2025-07-17T09:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerApiKeyAuth: []
components:
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 1000
      description: >-
        The maximum number of requests that you can make in the current rate
        limit window.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 998
      description: The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1747322958
      description: >-
        The time at which the current rate limit window resets, in UTC epoch
        seconds.
    Retry-After:
      schema:
        type: integer
        example: 60
      description: >-
        The number of seconds to wait before making a new request after hitting
        the rate limit.
  schemas:
    TSK_Task:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
          description: The title of the task.
          example: Follow up with John Doe
        description:
          type:
            - string
            - 'null'
          description: The description of the task, in markdown format.
          example: Discuss the Q3 proposal.
        entity:
          type: object
          properties:
            id:
              type: string
              minLength: 40
              maxLength: 40
            entityType:
              type: string
              enum:
                - person
                - company
                - object
              description: The type of entity connected to the task.
              example: person
            fullName:
              type: string
              maxLength: 1000
              description: The full name of the entity.
              example: John Doe
          required:
            - id
            - entityType
            - fullName
          description: >-
            The entity connected to the task. You can link people, companies and
            deals.
          example:
            id: per_55175e81-9a52-4ac3-930e-82792c23499b
            entityType: person
            fullName: John Doe
        recurrenceFrequency:
          type:
            - string
            - 'null'
          enum:
            - weekday
            - weekly
            - biweekly
            - monthly
            - quarterly
            - yearly
            - null
          description: >-
            The recurrence frequency of the task. One of: weekday, weekly,
            biweekly, monthly, quarterly, yearly. Null if non-recurring.
        dueAt:
          type: string
          minLength: 10
          maxLength: 10
          format: date
          description: The due date of the task, in YYYY-MM-DD format.
          example: '2025-07-17'
        dueTime:
          type:
            - string
            - 'null'
          minLength: 5
          maxLength: 5
          description: The due time of the task, in HH:mm format.
          example: '15:00'
        completedAt:
          type:
            - string
            - 'null'
          maxLength: 30
          format: date-time
          description: >-
            The date and time the task was completed, or null if not yet
            completed.
          example: '2025-07-17T09:00:00.000Z'
        isPublic:
          type: boolean
          description: >-
            Whether the task is visible to all workspace members (true) or only
            to its assigned users (false).
          example: true
        assignedUsers:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: The users assigned to this task.
        createdBy:
          allOf:
            - $ref: '#/components/schemas/User'
            - description: The user who created the task.
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - title
        - description
        - entity
        - recurrenceFrequency
        - dueAt
        - dueTime
        - completedAt
        - isPublic
        - assignedUsers
        - createdBy
        - createdAt
        - updatedAt
      description: A task created by a user.
      example:
        id: tsk_91118b73-5a75-480b-b8e3-a33671c35cdc
        title: Follow up with John Doe
        description: Discuss the Q3 proposal.
        entity:
          id: per_55175e81-9a52-4ac3-930e-82792c23499b
          entityType: person
          fullName: John Doe
        dueAt: '2025-07-17'
        dueTime: '15:00'
        completedAt: null
        recurrenceFrequency: null
        isPublic: true
        assignedUsers:
          - id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
            fullName: John Doe
            email: john.doe@example.com
        createdBy:
          id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
          fullName: John Doe
          email: john.doe@example.com
        createdAt: '2025-07-17T09:00:00.000Z'
        updatedAt: '2025-07-17T09:00:00.000Z'
    User:
      type: object
      properties:
        id:
          type: string
        fullName:
          type: string
        email:
          type: string
      required:
        - id
        - fullName
        - email
      description: A user in the workspace.
      example:
        id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
        fullName: John Doe
        email: john.doe@example.com
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              additionalProperties: true
              example:
                limit: 1000
                remaining: 0
                retryAfter: '2025-10-01T12:00:00Z'
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
      required:
        - error
      description: Error response containing error details.
  responses:
    BadRequest:
      description: The request was unacceptable, often due to missing an invalid parameter.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_REQUEST
              message: The request was invalid.
              documentationUrl: https://developer.folk.app/api-reference/errors#bad-request
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Unauthorized:
      description: No valid API key provided.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: No valid API key provided.
              documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Forbidden:
      description: The API key doesn’t have permissions to perform the request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: The API key doesn’t have permissions to perform the request.
              documentationUrl: https://developer.folk.app/api-reference/errors#forbidden
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    NotFound:
      description: The requested resource doesn’t exist.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              documentationUrl: https://developer.folk.app/api-reference/errors#not-found
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    UnprocessableEntity:
      description: >-
        The request was unacceptable, often due to missing or invalid
        parameters.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNPROCESSABLE_ENTITY
              message: Invalid query parameters
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#unprocessable-entity
              details:
                issues:
                  - code: too_small
                    minimum: 1
                    type: number
                    inclusive: true
                    exact: false
                    message: Number must be greater than or equal to 1
                    path:
                      - limit
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    TooManyRequests:
      description: >-
        Too many requests hit the API too quickly. We recommend an exponential
        backoff of your requests.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RATE_LIMIT_EXCEEDED
              message: The rate limit has been exceeded.
              documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
              details:
                limit: 1000
                remaining: 0
                retryAfter: '2025-10-01T12:00:00Z'
    InternalServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An internal server error occurred.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#internal-server-error
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    ServiceUnavailable:
      description: The server is overloaded or down for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SERVICE_UNAVAILABLE
              message: The service is currently unavailable.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#service-unavailable
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
  securitySchemes:
    bearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````