clearml-server/apiserver/schema/services/reports.conf

_description: "Provides a management API for reports in the system."
_definitions {
    include "_tasks_common.conf"
    include "_events_common.conf"
    update_response {
        type: object
        properties {
            updated {
                description: "Number of reports updated (0 or 1)"
                type: integer
                enum: [ 0, 1 ]
            }
            fields {
                description: "Updated fields names and values"
                type: object
                additionalProperties: true
            }
        }
    }
    report_status_enum {
        type: string
        enum: [
            created
            published
        ]
    }
    report {
        type: object
        properties {
            id {
                description: "Report id"
                type: string
            }
            name {
                description: "Report Name"
                type: string
            }
            user {
                description: "Associated user id"
                type: string
            }
            company {
                description: "Company ID"
                type: string
            }
            status {
                description: ""
                "$ref": "#/definitions/report_status_enum"
            }
            comment {
                description: "Free text comment"
                type: string
            }
            report {
                description: "Report template"
                type: string
            }
            created {
                description: "Report creation time (UTC) "
                type: string
                format: "date-time"
            }
            project {
                description: "Project ID of the project to which this report is assigned"
                type: string
            }
            tags {
                description: "User-defined tags list"
                type: array
                items { type: string }
            }
            system_tags {
                description: "System tags list. This field is reserved for system use, please don't use it."
                type: array
                items { type: string }
            }
            status_changed {
                description: "Last status change time"
                type: string
                format: "date-time"
            }
            status_message {
                description: "free text string representing info about the status"
                type: string
            }
            status_reason {
                description: "Reason for last status change"
                type: string
            }
            published {
                description: "Report publish time"
                type: string
                format: "date-time"
            }
            last_update {
                description: "Last time this report was created, edited, changed"
                type: string
                format: "date-time"
            }
        }
    }
}
create {
    "999.0" {
        description: "Create a new report"
        request {
            type: object
            required: [
                name
            ]
            properties {
                name {
                    description: "Report name. Unique within the company."
                    type: string
                }
                tags {
                    description: "User-defined tags list"
                    type: array
                    items { type: string }
                }
                comment {
                    description: "Free text comment "
                    type: string
                }
                report {
                    description: "Report template"
                    type: string
                }
                project {
                    description: "Project ID of the project to which this report is assigned Must exist[ab]"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                id {
                    description: "ID of the report"
                    type: string
                }
                project_id {
                    description: "ID of the project that the report belongs to"
                    type: string
                }
            }
        }
    }
}
update {
    "999.0" {
        description: "Create a new report"
        request {
            type: object
            required: [
                task
            ]
            properties {
                task {
                    description: "The ID of the report task to update"
                    type: string
                }
                name {
                    description: "Report name. Unique within the company."
                    type: string
                }
                tags {
                    description: "User-defined tags list"
                    type: array
                    items { type: string }
                }
                comment {
                    description: "Free text comment "
                    type: string
                }
                report {
                    description: "Report template"
                    type: string
                }
            }
        }
        response: ${_definitions.update_response}
    }
}
move {
    "999.0" {
        description: "Move reports to a project"
        request {
            type: object
            required: [task]
            properties {
                task {
                    description: "ID of the report to move"
                    type: string
                }
                project {
                    description: "Target project ID. If not provided, `project_name` must be provided."
                    type: string
                }
                project_name {
                    description: "Target project name. If provided and a project with this name does not exist, a new project will be created. If not provided, `project` must be provided."
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                project_id: {
                    description: The ID of the target project
                    type: string
                }
            }
        }
    }
}
publish {
    "999.0" {
        description: "Publish report"
        request {
            type: object
            required: [
                task
            ]
            properties {
                task {
                    description: "The ID of the report task to publish"
                    type: string
                }
                comment {
                    description: "The client message"
                    type: string
                }
            }
        }
        response: ${_definitions.update_response}
    }
}
archive {
    "999.0" {
        description: "Archive report"
        request {
            type: object
            required: [
                task
            ]
            properties {
                task {
                    description: "The ID of the report task to archive"
                    type: string
                }
                comment {
                    description: "The client message"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                archived {
                    description: "Number of reports archived (0 or 1)"
                    type: integer
                    enum: [0, 1]
                }
            }
        }
    }
}
unarchive {
    "999.0" {
        description: "Unarchive report"
        request {
            type: object
            required: [
                task
            ]
            properties {
                task {
                    description: "The ID of the report task to unarchive"
                    type: string
                }
                comment {
                    description: "The client message"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                unarchived {
                    description: "Number of reports unarchived (0 or 1)"
                    type: integer
                    enum: [0, 1]
                }
            }
        }
    }
}
//share {
//    "999.0" {
//        description: "Share or unshare report"
//        request {
//            type: object
//            required: [
//                task
//            ]
//            properties {
//                task {
//                    description: "The ID of the report task to share/unshare"
//                    type: string
//                }
//                share {
//                    description: "If set to 'true' then the report will be shared. Otherwise unshared."
//                    type: boolean
//                    default: true
//                }
//            }
//        }
//        response {
//            type: object
//            properties {
//                changed {
//                    description: "Number of changed reports (0 or 1)"
//                    type: integer
//                    enum: [0, 1]
//                }
//            }
//        }
//    }
//}
delete {
    "999.0" {
        description: "Delete report"
        request {
            type: object
            required: [
                task
            ]
            properties {
                task {
                    description: "The ID of the report task to delete"
                    type: string
                }
                force {
                    description: "If not set then published or unarchived reports cannot be deleted"
                    type: boolean
                    default: false
                }
            }
        }
        response {
            type: object
            properties {
                deleted {
                    description: "Number of deleted reports (0 or 1)"
                    type: integer
                    enum: [0, 1]
                }
            }
        }
    }
}
get_task_data {
    "999.0" {
        description: "Get the tasks data according the passed search criteria + requested events"
        request {
            type: object
            properties {
                id {
                    description: "List of IDs to filter by"
                    type: array
                    items { type: string }
                }
                name {
                    description: "Get only tasks whose name matches this pattern (python regular expression syntax)"
                    type: string
                }
                user {
                    description: "List of user IDs used to filter results by the task's creating user"
                    type: array
                    items { type: string }
                }
                size {
                    type: integer
                    minimum: 1
                    description: "The number of tasks to retrieve"
                }
                order_by {
                    description: "List of field names to order by. When search_text is used, '@text_score' can be used as a field representing the text score of returned documents. Use '-' prefix to specify descending order. Optional, recommended when using page"
                    type: array
                    items { type: string }
                }
                type {
                    description: "List of task types. One or more of: 'import', 'annotation', 'training' or 'testing' (case insensitive)"
                    type: array
                    items { type: string }
                }
                tags {
                    description: "List of task user-defined tags. Use '-' prefix to exclude tags"
                    type: array
                    items { type: string }
                }
                system_tags {
                    description: "List of task system tags. Use '-' prefix to exclude system tags"
                    type: array
                    items { type: string }
                }
                status {
                    description: "List of task status."
                    type: array
                    items { "$ref": "#/definitions/task_status_enum" }
                }
                project {
                    description: "List of project IDs"
                    type: array
                    items { type: string }
                }
                only_fields {
                    description: "List of task field names (nesting is supported using '.', e.g. execution.model_labels). If provided, this list defines the query's projection (only these fields will be returned for each result entry)"
                    type: array
                    items { type: string }
                }
                parent {
                    description: "Parent ID"
                    type: string
                }
                status_changed {
                    description: "List of status changed constraint strings (utcformat, epoch) with an optional prefix modifier (>, >=, <, <=)"
                    type: array
                    items {
                        type: string
                        pattern: "^(>=|>|<=|<)?.*$"
                    }
                }
                search_text {
                    description: "Free text search query"
                    type: string
                }
                allow_public {
                    description: "Allow public tasks to be returned in the results"
                    type: boolean
                    default: true
                }
                _all_ {
                    description: "Multi-field pattern condition (all fields match pattern)"
                    "$ref": "#/definitions/multi_field_pattern_data"
                }
                _any_ {
                    description: "Multi-field pattern condition (any field matches pattern)"
                    "$ref": "#/definitions/multi_field_pattern_data"
                }
                "input.view.entries.dataset" {
                    description: "List of input dataset IDs"
                    type: array
                    items { type: string }
                }
                "input.view.entries.version" {
                    description: "List of input dataset version IDs"
                    type: array
                    items { type: string }
                }
                search_hidden {
                    description: "If set to 'true' then hidden tasks are included in the search results"
                    type: boolean
                    default: false
                }
                include_subprojects {
                    description: "If set to 'true' and project field is set then tasks from the subprojects are searched too"
                    type: boolean
                    default: false
                }
                plots {
                    type: object
                    properties {
                        iters {
                            type: integer
                            description: "Max number of latest iterations for which to return plots"
                        }
                        metrics {
                            type: array
                            description: List of metrics and variants
                            items { "$ref": "#/definitions/metric_variants" }
                        }
                    }
                }
                debug_images {
                    type: object
                    properties {
                        iters {
                            type: integer
                            description: "Max number of latest iterations for which to return debug images"
                        }
                        metrics {
                            type: array
                            description: List of metrics and variants
                            items { "$ref": "#/definitions/metric_variants" }
                        }
                    }
                }
                scalar_metrics_iter_histogram {
                    type: object
                    properties {
                        samples {
                            description: "The amount of histogram points to return (0 to return all the points). Optional, the default value is 6000."
                            type: integer
                        }
                        key {
                            description: """
                            Histogram x axis to use:
                            iter - iteration number
                            iso_time - event time as ISO formatted string
                            timestamp - event timestamp as milliseconds since epoch
                            """
                            "$ref": "#/definitions/scalar_key_enum"
                        }
                        metrics {
                            type: array
                            description: List of metrics and variants
                            items { "$ref": "#/definitions/metric_variants" }
                        }
                    }
                }
            }
        }
        response {
            type: object
            properties {
                tasks {
                    description: "List of tasks"
                    type: array
                    items { "$ref": "#/definitions/task" }
                }
                plots {
                    type: object
                    description: "Plots mapped by metric, variant, task and iteration"
                    additionalProperties: true
                }
                debug_images {
                    type: array
                    description: "Debug image events grouped by tasks and iterations"
                    items {"$ref": "#/definitions/debug_images_response_task_metrics"}
                }
                scalar_metrics_iter_histogram {
                    type: object
                    additionalProperties: true
                }
            }
        }
    }
}
get_all_ex {
    "999.0" {
        description: "Get all the company's and public report tasks"
        request {
            type: object
            properties {
                id {
                    description: "List of IDs to filter by"
                    type: array
                    items { type: string }
                }
                name {
                    description: "Get only reports whose name matches this pattern (python regular expression syntax)"
                    type: string
                }
                user {
                    description: "List of user IDs used to filter results by the reports's creating user"
                    type: array
                    items { type: string }
                }
                page {
                    description: "Page number, returns a specific page out of the resulting list of reports"
                    type: integer
                    minimum: 0
                }
                page_size {
                    description: "Page size, specifies the number of results returned in each page (last page may contain fewer results)"
                    type: integer
                    minimum: 1
                }
                order_by {
                    description: "List of field names to order by. When search_text is used, '@text_score' can be used as a field representing the text score of returned documents. Use '-' prefix to specify descending order. Optional, recommended when using page"
                    type: array
                    items { type: string }
                }
                tags {
                    description: "List of report user-defined tags. Use '-' prefix to exclude tags"
                    type: array
                    items { type: string }
                }
                system_tags {
                    description: "List of report system tags. Use '-' prefix to exclude system tags"
                    type: array
                    items { type: string }
                }
                status {
                    description: "List of report status."
                    type: array
                    items { "$ref": "#/definitions/report_status_enum" }
                }
                project {
                    description: "List of project IDs"
                    type: array
                    items { type: string }
                }
                only_fields {
                    description: "List of report field names (nesting is supported using '.'). If provided, this list defines the query's projection (only these fields will be returned for each result entry)"
                    type: array
                    items { type: string }
                }
                status_changed {
                    description: "List of status changed constraint strings (utcformat, epoch) with an optional prefix modifier (>, >=, <, <=)"
                    type: array
                    items {
                        type: string
                        pattern: "^(>=|>|<=|<)?.*$"
                    }
                }
                search_text {
                    description: "Free text search query"
                    type: string
                }
                scroll_id {
                    type: string
                    description: "Scroll ID returned from the previos calls to get_all"
                }
                refresh_scroll {
                    type: boolean
                    description: "If set then all the data received with this scroll will be requeried"
                }
                size {
                    type: integer
                    minimum: 1
                    description: "The number of tasks to retrieve"
                }
                allow_public {
                    description: "Allow public reports to be returned in the results"
                    type: boolean
                    default: true
                }
                _all_ {
                    description: "Multi-field pattern condition (all fields match pattern)"
                    "$ref": "#/definitions/multi_field_pattern_data"
                }
                _any_ {
                    description: "Multi-field pattern condition (any field matches pattern)"
                    "$ref": "#/definitions/multi_field_pattern_data"
                }
            }
            dependencies {
                page: [ page_size ]
            }
        }
        response {
            type: object
            properties {
                tasks {
                    description: "List of report tasks"
                    type: array
                    items { "$ref": "#/definitions/report" }
                }
                scroll_id {
                    type: string
                    description: "Scroll ID that can be used with the next calls to get_all to retrieve more data"
                }
            }
        }
    }
}
get_tags {
    "999.0" {
        description: "Get all the user tags used for the company reports"
        request {
            type: object
            additionalProperties: false
        }
        response {
            type: object
            properties {
                tags {
                    description: "The list of unique tag values"
                    type: array
                    items {type: string}
                }
            }
        }
    }
}