TileDB Task Graph Logs API

openapi: 3.2.0
info:
  description: TileDB Storage Platform REST API
  title: TileDB Storage Platform Task Graph Logs API
  version: 2.17.51
servers:
- url: /v1
security:
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: task_graph_logs
paths:
  /taskgraphs/{namespace}/log:
    post:
      description: Create a task graph log.
      operationId: createTaskGraphLog
      tags:
      - task_graph_logs
      parameters:
      - name: namespace
        in: path
        description: The namespace that will own this task graph log.
        required: true
        schema:
          type: string
      responses:
        201:
          description: 'The task graph was created. The returned TaskGraphLog will include the data the client sent, with the server-defined fields added in.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskGraphLog'
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskGraphLog'
        required: true
      summary: Create task graph log
      x-summary-source: derived
  /taskgraphs/logs:
    parameters:
    - name: namespace
      in: query
      description: Include logs for this namespace.
      required: false
      schema:
        type: string
    - name: created_by
      in: query
      description: Include logs from only this user.
      required: false
      schema:
        type: string
    - name: status
      in: query
      description: Filter to only return these statuses
      required: false
      schema:
        type: string
    - name: search
      in: query
      description: search string that will look at name.
      required: false
      schema:
        type: string
    - name: start_time
      in: query
      description: Include logs created after this time.
      required: false
      schema:
        type: string
        format: date-time
    - name: end_time
      in: query
      description: Include logs created before this time.
      required: false
      schema:
        type: string
        format: date-time
    - name: page
      in: query
      description: pagination offset
      required: false
      schema:
        type: integer
    - name: per_page
      in: query
      description: pagination limit
      required: false
      schema:
        type: integer
    get:
      description: 'Fetch the task graph logs of a namespace the user has access to. The returned entries will include only summary data, and will not include information about the individual tasks that were executed. (This information is available when requesting an individual task graph log.)

        Entries in the response are ordered from newest to oldest. Pagination parameters work as in other API methods; see PaginationMetadata.'
      operationId: listTaskGraphLogs
      tags:
      - task_graph_logs
      responses:
        200:
          description: The task graph logs that matched the user's query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskGraphLogsData'
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: List task graph logs
      x-summary-source: derived
  /taskgraphs/{namespace}/logs/{id}:
    parameters:
    - name: namespace
      in: path
      description: The namespace that owns this task graph log.
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: The UUID of the task graph log entry.
      required: true
      schema:
        type: string
    get:
      description: Fetch information about a single task graph execution.
      operationId: getTaskGraphLog
      tags:
      - task_graph_logs
      responses:
        200:
          description: Information about the execution of a single task graph.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskGraphLog'
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get task graph log
      x-summary-source: derived
    patch:
      description: Update information about a single task graph execution.
      operationId: updateTaskGraphLog
      tags:
      - task_graph_logs
      responses:
        204:
          description: Log entry updated successfully.
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskGraphLog'
        description: 'Updates to make to the task graph log. The only manual update that a client should need to make to a task graph log is to update its completion status to `succeeded`, `failed`, or `cancelled`.

          '
        required: true
      summary: Update task graph log
      x-summary-source: derived
  /taskgraphs/{namespace}/logs/{id}/report_client_node:
    parameters:
    - name: namespace
      in: path
      description: The namespace that owns this task graph log.
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: The UUID of the task graph log entry.
      required: true
      schema:
        type: string
    post:
      operationId: reportClientNode
      tags:
      - task_graph_logs
      responses:
        204:
          description: Status reported successfully.
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskGraphClientNodeStatus'
        description: The node status to report.
        required: true
      summary: Report client node
      x-summary-source: derived
  /taskgraphs/{namespace}/executions/{id}/resubmit:
    parameters:
    - name: namespace
      in: path
      description: The namespace that owns this task graph execution.
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: The UUID of the task graph execution (TaskGraphLog).
      required: true
      schema:
        type: string
    post:
      description: Resubmits a task graph in the given namespace using the associated execution id.
      operationId: resubmitTaskGraphExecution
      tags:
      - task_graph_logs
      responses:
        202:
          description: Information about the task graph execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskGraphLog'
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Resubmit task graph execution
      x-summary-source: derived
  /taskgraphs/{namespace}/executions/{id}/retry:
    parameters:
    - name: namespace
      in: path
      description: The namespace that owns this task graph execution.
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: The UUID of the task graph execution (TaskGraphLog).
      required: true
      schema:
        type: string
    post:
      description: Retries failed tasks of a task graph in the given namespace using the associated execution id.
      operationId: retryTaskGraphExecution
      tags:
      - task_graph_logs
      responses:
        202:
          description: Information about the task graph execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskGraphLog'
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Retry task graph execution
      x-summary-source: derived
  /taskgraphs/{namespace}/executions/{id}/stop:
    parameters:
    - name: namespace
      in: path
      description: The namespace that owns this task graph execution.
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: The UUID of the task graph execution (TaskGraphLog).
      required: true
      schema:
        type: string
    post:
      description: Stops a task graph execution in the given namespace using the associated associated execution id.
      operationId: stopTaskGraphExecution
      tags:
      - task_graph_logs
      responses:
        204:
          description: Graph stopped successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Stop task graph execution
      x-summary-source: derived
  /taskgraphs/{namespace}/graphs/{id}/submit:
    parameters:
    - name: namespace
      in: path
      description: The namespace that owns this task graph.
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: The UUID of the task graph entry.
      required: true
      schema:
        type: string
    post:
      description: Submit a single task graph for execution.
      operationId: submitTaskGraph
      tags:
      - task_graph_logs
      responses:
        202:
          description: Information about the execution of a single task graph.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskGraphLog'
        502:
          description: Bad Gateway
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Submit task graph
      x-summary-source: derived
components:
  schemas:
    Querytype:
      description: Type of query
      type: string
      enum:
      - READ
      - WRITE
      - DELETE
    PricingCurrency:
      description: Currency of pricing
      type: string
      enum:
      - USD
    Subscription:
      description: Subscription of a user (customer) to another user's arrays
      type: object
      properties:
        id:
          description: Unique ID of subscription as defined by Stripe
          type: string
          example: subscriptionID
        owner_namespace_uuid:
          description: Unique ID of the array (product) owner
          type: string
          example: 00000000-0000-0000-0000-000000000000
        customer_namespace_uuid:
          description: Unique ID of the array (product) user (customer)
          type: string
          example: 00000000-0000-0000-0000-000000000000
        pricing:
          description: list of pricing used by this subscription
          type: array
          x-omitempty: true
          items:
            $ref: '#/components/schemas/Pricing'
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int64
        message:
          type: string
        request_id:
          type: string
    ArrayTaskType:
      description: Synchronous Task Type
      type: string
      enum:
      - SQL
      - UDF
      - QUERY
      - GENERIC_UDF
      - BATCH_UDF
      - CLIENT_COMPUTATION
    ResultFormat:
      description: Data format of a result
      type: string
      enum:
      - python_pickle
      - r_serialization
      - json
      - arrow
      - bytes
      - tiledb_json
      - native
    DomainArray:
      description: Domain object for an array of each type
      type: object
      properties:
        int8:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: int8
        uint8:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: uint8
        int16:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: int16
        uint16:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: uint16
        int32:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: int32
        uint32:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: uint32
        int64:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: int64
        uint64:
          type: array
          x-omitempty: true
          items:
            type: integer
            format: uint64
        float32:
          type: array
          x-omitempty: true
          items:
            type: number
            format: float
        float64:
          type: array
          x-omitempty: true
          items:
            type: number
            format: double
    TaskGraphNodeMetadata:
      description: Metadata about an individual node in a task graph.
      type: object
      properties:
        client_node_uuid:
          type: string
          description: The client-generated UUID of the given graph node.
        name:
          type: string
          maxLength: 255
          description: 'The client-generated name of the node. This is not guaranteed to be unique.

            '
        depends_on:
          type: array
          items:
            type: string
          description: 'The client_node_uuid of each node that this node depends upon. Used to define the structure of the graph.

            '
        run_location:
          $ref: '#/components/schemas/TaskGraphLogRunLocation'
        status:
          description: 'If present, the overall execution status of this node, taking into account the latest execution information.

            For nodes that have not yet been executed, this will be listed as `QUEUED`. For nodes that are set to run locally and have not reported any status information, this will be listed as `UNKNOWN`.

            '
          $ref: '#/components/schemas/ArrayTaskStatus'
        status_message:
          description: The reason the array task status is in the state
          type:
          - string
          - 'null'
          x-omitempty: true
        executions:
          type: array
          items:
            $ref: '#/components/schemas/ArrayTask'
          readOnly: true
          description: 'ArrayTasks representing each execution attempt for this node. For nodes that have never been submitted, this will be empty. For nodes that have been retried, this may have multiple entries. The last one in the list represents the most recent execution.

            This is read-only and generated by the server based on the tasks it has actually executed.

            '
    MetadataStringifiedEntry:
      type: object
      description: key/value pair representing an asset metadata map entry
      properties:
        key:
          description: The metadata key
          type: string
          x-omitempty: false
        value:
          description: The metadata value
          type: string
          x-omitempty: false
        type:
          description: The metadata type
          type: string
          x-omitempty: false
          example: array_metadata
    Pricing:
      description: Pricing created by converting an array to product
      type: object
      properties:
        id:
          description: Unique ID of plan as defined by Stripe
          type: string
          example: planID
        array_uuid:
          description: Unique ID of registered array
          type: string
          example: 00000000-0000-0000-0000-000000000000
        pricing_name:
          description: Name of pricing
          type: string
        pricing_type:
          description: Type of pricing
          $ref: '#/components/schemas/PricingType'
        product_name:
          description: Name of product
          type: string
        product_statement_descriptor:
          description: Extra information about a product which will appear on the credit card statement of the customer
          type: string
        product_unit_label:
          description: A label that represents units of this product in Stripe and receipts and invoices of the customer
          $ref: '#/components/schemas/PricingUnitLabel'
        currency:
          description: Currency of pricing
          $ref: '#/components/schemas/PricingCurrency'
        aggregate_usage:
          description: Specifies a usage aggregation strategy for pricings of usage_type=metered
          $ref: '#/components/schemas/PricingAggregateUsage'
        interval:
          description: The frequency with which a subscription should be billed
          $ref: '#/components/schemas/PricingInterval'
        divided_by:
          description: Group of n product unit labels
          type: integer
          format: int64
          example: 1048576
        charge:
          description: Price in cents (decimal) per unitlabel
          type: number
          format: double
        activated:
          description: If pricing is activated
          type: boolean
          example: false
    ArrayTaskStatus:
      description: Status of array task
      type: string
      enum:
      - QUEUED
      - FAILED
      - COMPLETED
      - RUNNING
      - RESOURCES_UNAVAILABLE
      - UNKNOWN
      - CANCELLED
      - DENIED
    TaskGraphClientNodeStatus:
      description: 'A report of the execution status of a node that ran on the client side.

        '
      type: object
      properties:
        client_node_uuid:
          type: string
        status:
          $ref: '#/components/schemas/ArrayTaskStatus'
    PricingUnitLabel:
      description: Unit label
      type: string
      enum:
      - byte
      - second
    FileType:
      description: File types represented as TileDB arrays
      type: string
      enum:
      - notebook
      - user_defined_function
      - ml_model
      - file
      - registered_task_graph
    ArrayActivityLog:
      description: Actvity of an Array
      type: object
      properties:
        event_at:
          description: time event took place (RFC3339)
          type: string
          format: date-time
        action:
          description: Type of the event
          $ref: '#/components/schemas/ActivityEventType'
        username:
          description: User who performed action
          type: string
          example: user1
        bytes_sent:
          description: Bytes sent to client
          type: integer
          format: uint64
          example: 1073741824
        bytes_received:
          description: Bytes recieved from client
          type: integer
          format: uint64
          example: 1073741824
        array_task_id:
          description: UUID of associated array task
          type: string
          example: 00000000-0000-0000-0000-000000000000
        id:
          description: ID of the activity
          type: string
          example: 00000000-0000-0000-0000-000000000000
        query_ranges:
          description: ranges for query
          x-omitempty: true
          type: string
          example: '{"rows":[{"start": 1, "end": 1},{"start": 3, "end": 4}],"cols":[{"start": 1, "end": 4}]}'
        query_stats:
          description: stats for query
          x-omitempty: true
          type: string
          example: '{"timers": {"Context.StorageManager.read_load_array_schema_from_uri.sum": 0.0255293, "...": "..."}, "counters": {"Context.StorageManager.read_unfiltered_byte_num": 191, "...": "..."}}'
    PricingInterval:
      description: Interval for pricing
      type: string
      enum:
      - month
    TaskGraphLogsData:
      description: Response data for a task graph list, including pagination metadata.
      type: object
      properties:
        task_graph_logs:
          description: The requested task graph logs.
          type: array
          items:
            $ref: '#/components/schemas/TaskGraphLog'
        pagination_metadata:
          $ref: '#/components/schemas/PaginationMetadata'
    ArrayTask:
      description: Synchronous Task to Run
      type: object
      properties:
        id:
          description: task ID
          type: string
        name:
          description: Optional task name
          type: string
          example: subarray-multiplier
        username:
          description: username that executed this task
          type: string
          example: demo
        description:
          description: Optional task description (Tasks purpose)
          type: string
          example: Return attr a1 in the subarray bounded by coordinates and multiply attr1 by 2
        array_metadata:
          description: Metadata of the array used in the context of this task
          $ref: '#/components/schemas/ArrayInfo'
        subarray:
          description: A subarray to run the array task on
          $ref: '#/components/schemas/DomainArray'
          example:
          - Dim1:
              Int64: 0 10
            Dim2:
              Int64: 20 22
            Dim3:
              Int64: 10000 10100
        memory:
          description: memory allocated to task in bytes
          type: integer
          format: uint64
          example: 1073741824
        cpu:
          description: millicpu allocated to task
          type: integer
          format: uint64
          example: 4000
        namespace:
          type: string
          description: namespace task is tied to
          example: organization1
        status:
          description: The status of an individual task
          $ref: '#/components/schemas/ArrayTaskStatus'
        status_message:
          description: The reason the array task status is in the state
          type:
          - string
          - 'null'
          x-omitempty: true
        start_time:
          description: Start time RFC3339 for job
          type:
          - string
          - 'null'
          format: date-time
        finish_time:
          description: Finish time RFC3339 for job
          type:
          - string
          - 'null'
          format: date-time
        cost:
          description: Total accumulated for task in USD, example is $0.12
          type: number
          format: double
          example: 0.12
        egress_cost:
          description: Total accumulated for egress task in USD, example is $0.12
          type: number
          format: double
          example: 0.12
        access_cost:
          description: Cost accumulated for access task in USD, example is $0.12
          type: number
          format: double
          example: 0.12
        query_type:
          description: If task type is query, whether it's a read or write query
          $ref: '#/components/schemas/Querytype'
        udf_code:
          description: Optional actual code that is going to be executed
          type: string
        udf_language:
          description: Optional actual language used to express udf_code
          type: string
        sql_query:
          description: Optional actual sql query that is going to be executed
          type: string
        type:
          description: Type of task
          $ref: '#/components/schemas/ArrayTaskType'
        activity:
          description: Array activity logs for task
          type: array
          x-omitempty: true
          items:
            $ref: '#/components/schemas/ArrayActivityLog'
        logs:
          description: logs from array task
          type: string
          x-omitempty: false
        duration:
          description: duration in nanoseconds of an array task
          type: number
          example: 341000000000
        sql_init_commands:
          description: SQL queries or commands to run before main sql query
          type: array
          items:
            type: string
            description: sql query or command to run before main sql query
        sql_parameters:
          description: SQL query parameters
          type: array
          items: {}
        result_format:
          $ref: '#/components/schemas/ResultFormat'
          description: type of results (native, i.e cloud pickle or json or arrow)
          x-omitempty: true
        task_graph_uuid:
          type: string
          x-omitempty: true
          description: 'If set, the ID of the log for the task graph that this was part of.

            '
        client_node_uuid:
          type: string
          x-omitempty: true
          description: 'If set, the client-defined ID of the node within this task''s graph.

            '
        cloud_provider:
          type: string
          x-omitempty: true
          description: The name of the cloud provider where this task executed.
        cloud_region:
          type: string
          x-omitempty: true
          description: The region of the cloud provider where this task executed.
    PricingType:
      description: Pricing types
      type: string
      enum:
      - egress
      - access
    ArrayActions:
      description: actions a user can take on an array
      type: string
      enum:
      - read
      - write
      - edit
      - read_array_logs
      - read_array_info
      - read_array_schema
    TaskGraphLog:
      description: Logging information about the execution of a task graph.
      type: object
      properties:
        uuid:
          type: string
          readOnly: true
          description: The server-generated UUID of the task graph.
        namespace:
          type: string
          description: 'The namespace that owns this task graph log. When creating a task graph log, this is used as the namespace to create the log in; thereafter it is read-only.

            '
        created_by:
          type: string
          readOnly: true
          description: The name of the user who created this task graph log.
        name:
          type: string
          description: 'A name for this task graph log, displayed in the UI. Does not need to be unique.

            '
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: 'The date/time when this task graph log was originally created. This is distinct from the execution start_time.

            '
        start_time:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          x-omitempty: true
          description: 'The start time of the task graph, recorded when the server starts executing the first node.

            '
        end_time:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          x-omitempty: true
          description: 'The end time of the task graph, recorded when the client reports completion.

            '
        status:
          $ref: '#/components/schemas/TaskGraphLogStatus'
        total_cost:
          type:
          - number
          - 'null'
          description: 'If present, the total cost of executing all nodes in this task graph.

            '
        access_cost:
          type:
          - number
          - 'null'
          description: 'If present, the total cost of access from execution of the nodes in this task graph.

            '
        egress_cost:
          type:
          - number
          - 'null'
          description: 'If present, the total cost of access from execution of the nodes in this task graph.

            '
        execution_time:
          type: string
          description: 'The total execution time of all the nodes in this graph, in ISO 8601 format with hours, minutes, and seconds.

            '
          example: P15H22M0.45S
        status_count:
          type: object
          description: 'A mapping from `ArrayTaskStatus` string value to the number of nodes in this graph that are in that status.

            '
          additionalProperties:
            description: The number of nodes that are in the given state.
            type: number
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/TaskGraphNodeMetadata'
          description: 'The structure of the graph. This is provided by the client when first setting up the task graph. Thereafter, it is read-only. This must be topographically sorted; that is, each node must appear after all nodes that it depends upon.

            '
        task_graph_type:
          $ref: '#/components/schemas/TaskGraphType'
        task_graph_id:
          type: string
          description: The UUID of the task graph.
        cloud_provider:
          type: string
          x-omitempty: true
          description: The name of the cloud provider where this task graph executed.
        cloud_region:
          type: string
          x-omitempty: true
          description: The region of the cloud provider where this task graph executed.
    TaskGraphLogRunLocation:
      description: 'The location where an individual node of a task graph is executed.

        '
      type: string
      enum:
      - server
      - client
      - virtual
    PricingAggregateUsage:
      description: Specifies a usage aggregation strategy for pricings of usage_type=metered
      type: string
      enum:
      - sum
    TaskGraphLogStatus:
      description: The status of a given task graph execution.
      type: string
      enum:
      - submitted
      - running
      - idle
      - abandoned
      - succeeded
      - failed
      - cancelled
    TaskGraphType:
      description: 'The type of a task graph.

        '
      type: string
      enum:
      - batch
      - realtime
    PaginationMetadata:
      properties:
        page:
          description: pagination offset. Use it to skip the first ((page - 1) * per_page) items
          type: number
          format: uint64
          example: 1
        per_page:
          description: pagination limit (page size)
          type: number
          format: uint64
          example: 10
        total_pages:
          description: number of total pages with current limit
          type: number
          format: uint64
          example: 14
        total_items:
          description: number of total available items
          type: number
          format: uint64
          example: 138
    ArrayType:
      description: TileDB array type
      type: string
      enum:
      - dense
      - sparse
    ActivityEventType:
      description: Type of activity logged
      type: string
      enum:
      - read_schema
      - max_buffer_sizes
      - non_empty_domain
      - query_read
      - query_write
      - query_delete
      - create
      - delete
      - register
      - deregister
      - udf
      - array_metadata_get
      - array_metadata_update
      - estimated_result_sizes
      - read_fragment_info
      - read_enumerations
    ArrayInfo:
      description: metadata of an array
      type: object
      properties:
        id:
          description: unique ID of registered array
          type: string
          example: 00000000-0000-0000-0000-000000000000
        file_type:
          description: File type stored /wrapped by this array
          x-omitempty: true
          $ref: '#/components/schemas/FileType'
        file_properties:
          type: object
          description: map of file properties created for this array
          x-omitempty: true
          additionalProperties:
            type: string
        uri:
          description: uri of array
          type: string
          exampl

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tiledb/refs/heads/main/openapi/tiledb-task-graph-logs-api-openapi.yml