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

# Get a list of tasks.

> Retrieve a paginated list of tasks filtered and sorted by criteria as specified in the query
params for the request.

Note that specifying an `offset` past the end of the list will result in an HTTP 200 response,
with the `offset` set to the value you specified, but `tasks` will be an empty list.



## OpenAPI

````yaml /api-reference/openapi.json get /task/list
openapi: 3.1.0
info:
  title: Synthpop API
  description: >-
    The Synthpop public API. Create and manage Tasks, upload documents, and
    retrieve structured results.
  version: 1.0.0pre
servers:
  - url: https://app.synthpop.ai/public/v1
    description: Production
  - url: https://stage.synthpop.ai/public/v1
    description: Staging
security: []
tags:
  - name: Authentication
    description: |-

      API endpoints to obtain credentials.
              
  - name: Tasks
    description: >

      API endpoints to create, update and fetch Tasks and Task metadata.


      All the endpoints in this section other than "Get File Download Link"
      return a `TaskDetail`

      object. It contains the following:

      * Summary information for the task, such as IDs, a user friendly name, the
      Task's current
        status and time stamps.
      * Data Items associated with the Task:
        * Data Items are either Text, JSON or a link to a file.
        * A Data Item has a `group` tag. Tasks will have an `inputs` group (for Data Items uploaded)
          or an `outputs` group (for Data Items generated). There might be other tags for
          intermediate output for specific types of Tasks.
        * When analyzing the content of a data item, the result of the analysis is represented as
          `record_groups` within the Data Item. Record groups have:
          * A Record Type, identifying the type of data detected (e.g: insurance card, patient
            form, ...)
          * An optional timestamp that is derived from the content, signifying when the record
            group was created (eg.: date of service for a clinical visit).
  - name: Task List
    description: Retrieve a filtered and ordered list of Tasks.
paths:
  /task/list:
    get:
      tags:
        - Task List
      summary: Get a list of tasks.
      description: >-
        Retrieve a paginated list of tasks filtered and sorted by criteria as
        specified in the query

        params for the request.


        Note that specifying an `offset` past the end of the list will result in
        an HTTP 200 response,

        with the `offset` set to the value you specified, but `tasks` will be an
        empty list.
      operationId: p_api_get_tasks_task_list_get
      parameters:
        - name: selected_date
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/DateFlavor'
            description: >-
              Specifies on what date (task creation or latest status change) the
              `date_from` and `date_to` limits should operate on. Default is
              `created`.
            default: created
          description: >-
            Specifies on what date (task creation or latest status change) the
            `date_from` and `date_to` limits should operate on. Default is
            `created`.
        - name: date_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
            description: >-
              Records with date or time stamps newer than this value, if
              specified.
            title: Date From
          description: >-
            Records with date or time stamps newer than this value, if
            specified.
        - name: date_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
            description: >-
              Records with date or time stamps up to and including this value,
              if specified.
            title: Date To
          description: >-
            Records with date or time stamps up to and including this value, if
            specified.
        - name: cleared
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Only return records with the `cleared` flag set/unset, if
              specified.
            title: Cleared
          description: Only return records with the `cleared` flag set/unset, if specified.
        - name: status
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TaskStatus'
            description: >-
              Only return records matching any of the specified task status
              values, if specified.
            default: []
            title: Status
          description: >-
            Only return records matching any of the specified task status
            values, if specified.
        - name: order_by
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/OrderBy'
            description: Sort criteria to use for the query.
            default: created
          description: Sort criteria to use for the query.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Start offset to use for records returned.
            default: 0
            title: Offset
          description: Start offset to use for records returned.
        - name: length
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Max. number of matching records to return from `offset`.
            default: 100
            title: Length
          description: Max. number of matching records to return from `offset`.
        - name: sort_ascending
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              If `true`, the sort order for the sort criteria is set to
              ascending. `false` or leaving this value unspecified will cause
              descending sort order to be used.
            default: false
            title: Sort Ascending
          description: >-
            If `true`, the sort order for the sort criteria is set to ascending.
            `false` or leaving this value unspecified will cause descending sort
            order to be used.
        - name: task_type
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            description: Only return records with specified task types, if specified.
            default: []
            title: Task Type
          description: Only return records with specified task types, if specified.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTasksResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - Bearer: []
components:
  schemas:
    DateFlavor:
      type: string
      enum:
        - created
        - latest_status_change
        - cleared
      title: DateFlavor
    TaskStatus:
      type: string
      enum:
        - pending
        - processing
        - waiting
        - completed
        - failed
        - invalid
        - deferred
      title: TaskStatus
      description: >-
        Current state of a task.


        - `pending`: The task is waiting to be processed.

        - `processing`: The task is currently being processed.

        - `waiting`: The task is waiting for additional input.

        - `completed`: The task has completed processing.

        - `failed`: An error occurred while the task was being processed.

        - `invalid`: The data uploaded does not provide any information
        pertaining to
           the task to be performed.
        - `deferred`: The bulk processing task has been put into a deferred
        state due to high load
    OrderBy:
      type: string
      enum:
        - created
        - latest_status_change
        - cleared
        - name
        - id
        - external_id
      title: OrderBy
      description: |-
        Sort criteria for list of task.
            
    GetTasksResponse:
      properties:
        count:
          type: integer
          title: Count
          description: Total number of matching tasks.
        offset:
          type: integer
          title: Offset
          description: >-
            Start offset within the sorted list of matching records for the data
            returned in this response.
        tasks:
          items:
            $ref: '#/components/schemas/TaskSummary'
          type: array
          title: Tasks
          description: >-
            List of matching tasks, filtered and sorted by the criteria in the
            request.
      type: object
      required:
        - count
        - offset
        - tasks
      title: GetTasksResponse
      description: Response from getting a list of tasks.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaskSummary:
      properties:
        uuid:
          type: string
          format: uuid
          title: Uuid
          description: A unique ID for the Task.
        external_id:
          anyOf:
            - type: string
              maxLength: 1024
            - type: 'null'
          title: External Id
          description: An optional third party assigned ID for the task.
        task_type:
          type: string
          title: Task Type
          description: >-
            A Task's type. Determines what kind of processing is performed on
            the input data.
        status:
          $ref: '#/components/schemas/TaskStatus'
        name:
          type: string
          title: Name
          description: A user friendly name, based on information extracted from inputs.
        cleared:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Cleared
          description: >-
            `cleared` can be set to a timestamp indicating when follow-ups (work
            external to Synthpop) related to this Task have been completed.
            Initialized to `null` upon Task creation.
        created:
          type: string
          format: date-time
          title: Created
          description: Timestamp indicating when this task was created.
        latest_status_change:
          type: string
          format: date-time
          title: Latest Status Change
          description: >-
            Timestamp indicating when the latest status change for this task
            occurred. This indicates when a Task entered `processing`,
            `waiting`, `completed` or `failed` state. For `pending` tasks this
            is set to the same value as `created`.
      type: object
      required:
        - uuid
        - task_type
        - status
        - name
        - cleared
        - created
        - latest_status_change
      title: TaskSummary
      description: A task's metadata summary.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````