--- title: "Create a job to generate a report" method: POST path: "/api/v3/teams/{team_slug}/reports/jobs" tags: ["Reports"] --- # Create a job to generate a report `POST /api/v3/teams/{team_slug}/reports/jobs` ## Request - Base URL: `https://darwin.v7labs.com` - URL: `https://darwin.v7labs.com/api/v3/teams/{team_slug}/reports/jobs` - Auth: one of: - HTTP bearer - API key in header `Authorization` Starts a background job to generate an 'annotator' or 'item' report. Immediately returns job info, containing the file URL to get the report from. Note: - The 'annotator' report data is available from 2024-11-05 - The 'item' report data is available from 2025-08-01 ## Path parameters - `team_slug` string, required ## Request body - ReportJobRequest: Job request information. - `dataset_ids` CommonIntegerId[], nullable - `filter` union - DatasetsV2AdvancedFiltersGroupFilter: Groups `simple` or `group filters` together with `or`, `and` operators. You have to specify at least one `filter`. - `conjunction` 'and' | 'or', required: Use to join filters together. It is possible to join simple or group filters with `and`, `or` operators - `filters` DatasetsV2AdvancedFiltersFilter[], required: List of `simple` or `group` filters - union: Filter can be `simple` or `group`. If you want to filter by one `subject` eg. `item name`. You can specify `simple filter` for given `subject` and `matcher`. For more details please see details of `item name filter` or other simple filters. If you want to to filter item by more than one filter You need to use `group filter` which gives possibility to join `filters` using `and`, `or` operators. - object: Groups `simple` or `group filters` together with `or`, `and` operators. You have to specify at least one `filter`. - `conjunction` 'and' | 'or', required: Use to join filters together. It is possible to join simple or group filters with `and`, `or` operators - `filters` DatasetsV2AdvancedFiltersFilter[], required: List of `simple` or `group` filters - DatasetsV2AdvancedFiltersAnnotationClassFilter: Filter items based on annotation class id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of annotation class ids For example if you would like to get `items` that don't have annotation class id: `[ 1 ]` you can specify matcher name: `none_of` and values: `[ 1 ]` - `matcher` union, required - … - `subject` 'annotation_class', required - DatasetsV2AdvancedFiltersArchivedFilter: Filter items based on archived status. If you want to see only archived items, you can set matcher name: `equals` and value: `true`. - `matcher` object, required: Matches items based on whether the values from the subject are equal to the one specified in the filter - … - `subject` 'archived', required - DatasetsV2AdvancedFiltersAssigneeFilter: Filter items based on assignee ids. You can filter using `any_of`, `none_of`, `all_of` matchers with list of assignee ids. We match assignees from all workflow stages besides current one. - `matcher` union, required - … - `subject` 'assignee', required - DatasetsV2AdvancedFiltersClassPropertyFilter: Filter items based on class property id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of class property ids For example if you would like to get `items` that don't have class property id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - … - `subject` 'class_property', required - DatasetsV2AdvancedFiltersClassPropertyValueFilter: Filter items based on class property value id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of class property value ids For example if you would like to get `items` that don't have class property value id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - … - `subject` 'class_property_value', required - DatasetsV2AdvancedFiltersItemPropertyFilter: Filter items based on item property id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of item property ids For example if you would like to get `items` that don't have item property id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - … - `subject` 'item_property', required - DatasetsV2AdvancedFiltersItemPropertyValueFilter: Filter items based on item property value id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of class property value ids For example if you would like to get `items` that don't have item property value id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - … - `subject` 'item_property_value', required - DatasetsV2AdvancedFiltersCreatedAtFilter: Filter items based creation date. You can filter items that were created `before` or `after`. You can also filter using range specified as `before`, `after`. Please keep in mind that `after` is inclusive while `before` is exclusive - `matcher` union, required: Matches items based on whether the values from the subject are in the range specified by before and/or after - … - `subject` 'created_at', required - DatasetsV2AdvancedFiltersCurrentAssigneeFilter: Filter items based on current assignee ids. You can filter using `any_of`, `none_of`, `all_of` matchers with list of current assignee ids. We match assignees from only current workflow stage. - `matcher` union, required - … - `subject` 'current_assignee', required - DatasetsV2AdvancedFiltersFileTypeFilter: Filter items based on file types it contains. If you are interested in items that contains specific file types you can specify matcher name: `any_of` values: `['image', 'video']`. - `matcher` union, required - … - `subject` 'file_type', required - DatasetsV2AdvancedFiltersFolderPathFilter: Filter items based on folder path. Each item exists in folder. If you want to see items only from folder `/folder1` you can specify matcher name: `any_of` and values: [`/folder1`]. If you want to see items from folders that name starts with provided values, You can specify matcher name: `prefix` or `not_prefix`. - `matcher` union, required - … - `subject` 'folder_path', required - DatasetsV2AdvancedFiltersIssueFilter: Filter items based on issue type. If you are interested in items that have comments, You can set matcher value to `comment`. You can specify matcher as `any_of` or `none_of`. - `matcher` union, required - … - `subject` 'issue', required - DatasetsV2AdvancedFiltersItemIdFilter: Filter items based on item id. If you want to get items with specific ids. You can specify matcher name: `any_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781', 'e23ff3f3-8f77-4e78-9e81-fdb25abfb782']` - `matcher` union, required - … - `subject` 'id', required - DatasetsV2AdvancedFiltersItemNameFilter: Filter items based on name. If you want to get items with specific name you can specify matcher name: `any_of`, values: `['name1', 'name2']`. You can also search for part of names using `prefix` or `contains` matchers. - `matcher` union, required - … - `subject` 'item_name', required - DatasetsV2AdvancedFiltersProcessingStatusFilter: Filter items based on processing status. Each item consists of one or more files that can be in states: `cancelled` | `error` | `uploading` | `upload_confirmed` | `processing` | `complete`. You can filter items that are in given state using matcher name: `any_of` values: `['cancelled', 'error']` - `matcher` union, required - … - `subject` 'processing_status', required - DatasetsV2AdvancedFiltersStatusFilter: Filter items based on status - this is temporary filter to support transitions on FE. Please do not use it. - `matcher` union, required - … - `subject` 'status', required - DatasetsV2AdvancedFiltersTextPropertyValueFilter: Filter items based on their text property values. You can filter using the `contains` matcher to search for text within a specific property. You must specify both the search value and the property_id to search within. - `matcher` object, required: Matches items based on whether the values from the subject contains the one specified in the filter - … - `subject` 'text_property_value', required - DatasetsV2AdvancedFiltersUpdatedAtFilter: Filter items based last update date. You can filter items that were updated `before` or `after`. You can also filter using range specified as `before`, `after`. Please keep in mind that `after` is inclusive while `before` is exclusive - `matcher` union, required: Matches items based on whether the values from the subject are in the range specified by before and/or after - … - `subject` 'updated_at', required - DatasetsV2AdvancedFiltersWorkflowStageFilter: Filter items based on workflow stage id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of workflow stage ids For example if you would like to get `items` that are not in workflow stage: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: [`e23ff3f3-8f77-4e78-9e81-fdb25abfb781`] - `matcher` union, required - … - `subject` 'workflow_stage', required - DatasetsV2AdvancedFiltersWorkflowStatusFilter: Filter items based on workflow status. If you want to get items that are in given workflow states you can specify matcher name: `any_of` values: `['new', 'annotate']`. - `matcher` union, required - … - `subject` 'workflow_status', required - DatasetsV2AdvancedFiltersWorkflowStageEnteredAtFilter: Filter items based on the entered date to a specific workflow stage provided in the `stage_id` field. You can filter items that were entered `before` or `after`. You can also filter using range specified as `before`, `after`. Please keep in mind that `after` is inclusive while `before` is exclusive - `matcher` union, required: Matches items based on stage id and whether the values from the subject are in the range specified by before and/or after - … - `subject` 'workflow_stage_entered_at', required - union: Simple filter specifies rule that subject has to fulfill. Each simple filter consist of `subject` and `matcher`. Subject is name of property you want to filter on. For example if you want to filter by item id you should specify {subject: 'item_id'}. Next you have to specify matcher which defines how you would like to filer. If you are interest in any of items within array of items id you should specify: {matcher: {name: 'any_of', values: [list of items ids]}} - object: Filter items based on annotation class id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of annotation class ids For example if you would like to get `items` that don't have annotation class id: `[ 1 ]` you can specify matcher name: `none_of` and values: `[ 1 ]` - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonIntegerId[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonIntegerId[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonIntegerId[], required - `subject` 'annotation_class', required - object: Filter items based on archived status. If you want to see only archived items, you can set matcher name: `equals` and value: `true`. - `matcher` object, required: Matches items based on whether the values from the subject are equal to the one specified in the filter - `name` 'equals', required - `value` boolean, required - `subject` 'archived', required - object: Filter items based on assignee ids. You can filter using `any_of`, `none_of`, `all_of` matchers with list of assignee ids. We match assignees from all workflow stages besides current one. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonIntegerId[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonIntegerId[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonIntegerId[], required - `subject` 'assignee', required - object: Filter items based on class property id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of class property ids For example if you would like to get `items` that don't have class property id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonUUID[], required - `subject` 'class_property', required - object: Filter items based on class property value id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of class property value ids For example if you would like to get `items` that don't have class property value id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonUUID[], required - `subject` 'class_property_value', required - object: Filter items based on item property id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of item property ids For example if you would like to get `items` that don't have item property id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonUUID[], required - `subject` 'item_property', required - object: Filter items based on item property value id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of class property value ids For example if you would like to get `items` that don't have item property value id: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonUUID[], required - `subject` 'item_property_value', required - object: Filter items based creation date. You can filter items that were created `before` or `after`. You can also filter using range specified as `before`, `after`. Please keep in mind that `after` is inclusive while `before` is exclusive - `matcher` union, required: Matches items based on whether the values from the subject are in the range specified by before and/or after - object - `before` string, date-time, required: DateTime in RFC3339 format - `name` 'date_range', required - object - `after` string, date-time, required: DateTime in RFC3339 format - `name` 'date_range', required - `subject` 'created_at', required - object: Filter items based on current assignee ids. You can filter using `any_of`, `none_of`, `all_of` matchers with list of current assignee ids. We match assignees from only current workflow stage. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonIntegerId[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonIntegerId[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonIntegerId[], required - `subject` 'current_assignee', required - object: Filter items based on file types it contains. If you are interested in items that contains specific file types you can specify matcher name: `any_of` values: `['image', 'video']`. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` string[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` string[], required - `subject` 'file_type', required - object: Filter items based on folder path. Each item exists in folder. If you want to see items only from folder `/folder1` you can specify matcher name: `any_of` and values: [`/folder1`]. If you want to see items from folders that name starts with provided values, You can specify matcher name: `prefix` or `not_prefix`. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` string[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` string[], required - object: Matches items based on whether the values from the subject starts with the one specified in the filter - `name` 'prefix', required - `value` string, required - object: Matches items based on whether the values from the subject does not start with the one specified in the filter - `name` 'not_prefix', required - `value` string, required - `subject` 'folder_path', required - object: Filter items based on issue type. If you are interested in items that have comments, You can set matcher value to `comment`. You can specify matcher as `any_of` or `none_of`. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` string[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` string[], required - `subject` 'issue', required - object: Filter items based on item id. If you want to get items with specific ids. You can specify matcher name: `any_of` and values: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781', 'e23ff3f3-8f77-4e78-9e81-fdb25abfb782']` - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonUUID[], required - `subject` 'id', required - object: Filter items based on name. If you want to get items with specific name you can specify matcher name: `any_of`, values: `['name1', 'name2']`. You can also search for part of names using `prefix` or `contains` matchers. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` string[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` string[], required - object: Matches items based on whether the values from the subject starts with the one specified in the filter - `name` 'prefix', required - `value` string, required - object: Matches items based on whether the values from the subject does not start with the one specified in the filter - `name` 'not_prefix', required - `value` string, required - object: Matches items based on whether the values from the subject contains the one specified in the filter - `name` 'contains', required - `value` string, required - object: Matches items based on whether the values from the subject does not contain the one specified in the filter - `name` 'not_contains', required - `value` string, required - `subject` 'item_name', required - object: Filter items based on processing status. Each item consists of one or more files that can be in states: `cancelled` | `error` | `uploading` | `upload_confirmed` | `processing` | `complete`. You can filter items that are in given state using matcher name: `any_of` values: `['cancelled', 'error']` - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` string[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` string[], required - `subject` 'processing_status', required - object: Filter items based on status - this is temporary filter to support transitions on FE. Please do not use it. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` string[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` string[], required - `subject` 'status', required - object: Filter items based on their text property values. You can filter using the `contains` matcher to search for text within a specific property. You must specify both the search value and the property_id to search within. - `matcher` object, required: Matches items based on whether the values from the subject contains the one specified in the filter - `name` 'contains', required - `value` object, required - `property_id` string, uuid, required - `value` string, required: The string to search by - `subject` 'text_property_value', required - object: Filter items based last update date. You can filter items that were updated `before` or `after`. You can also filter using range specified as `before`, `after`. Please keep in mind that `after` is inclusive while `before` is exclusive - `matcher` union, required: Matches items based on whether the values from the subject are in the range specified by before and/or after - object - `before` string, date-time, required: DateTime in RFC3339 format - `name` 'date_range', required - object - `after` string, date-time, required: DateTime in RFC3339 format - `name` 'date_range', required - `subject` 'updated_at', required - object: Filter items based on workflow stage id. You can filter using `any_of`, `none_of`, `all_of` matchers with list of workflow stage ids For example if you would like to get `items` that are not in workflow stage: `['e23ff3f3-8f77-4e78-9e81-fdb25abfb781']` you can specify matcher name: `none_of` and values: [`e23ff3f3-8f77-4e78-9e81-fdb25abfb781`] - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` CommonUUID[], required - object: Matches items based on whether the values from the subject are all in the values specified in the filter - `name` 'all_of', required - `values` CommonUUID[], required - `subject` 'workflow_stage', required - object: Filter items based on workflow status. If you want to get items that are in given workflow states you can specify matcher name: `any_of` values: `['new', 'annotate']`. - `matcher` union, required - object: Matches items based on whether the values from the subject have any of the values specified in the filter - `name` 'any_of', required - `values` string[], required - object: Matches items based on whether the values from the subject have none of the values specified in the filter - `name` 'none_of', required - `values` string[], required - `subject` 'workflow_status', required - object: Filter items based on the entered date to a specific workflow stage provided in the `stage_id` field. You can filter items that were entered `before` or `after`. You can also filter using range specified as `before`, `after`. Please keep in mind that `after` is inclusive while `before` is exclusive - `matcher` union, required: Matches items based on stage id and whether the values from the subject are in the range specified by before and/or after - object - `before` string, date-time, required: DateTime in RFC3339 format - `name` 'date_range', required - `stage_id` string, uuid, required - object - `after` string, date-time, required: DateTime in RFC3339 format - `name` 'date_range', required - `stage_id` string, uuid, required - `subject` 'workflow_stage_entered_at', required - object: Explicitly disable filtering - `all` true, required - `format` 'csv' | 'json': Report format. - `group_by` ReportGroupBy[], required: Types of grouping. - `metrics` ReportJobRequestMetricsItem[], required: Job request metrics. - `start` string, date-time, required: DateTime in RFC3339 format - `stop` string, date-time, required: DateTime in RFC3339 format - `type` 'annotator' | 'item': Report type. - `user_ids` CommonIntegerId[], nullable ## Response `200` Report.JobResponse - ReportJobResponse: Job response information. - `format` 'csv' | 'json', required: Report format. - `id` string, required - `inserted_at` string, date-time, required: DateTime in RFC3339 format - `owner_id` integer, nullable - `status` 'pending' | 'running' | 'finished' | 'failed', required - `team_id` integer, required - `type` 'annotator' | 'item' | 'storage', required - `updated_at` string, date-time, required: DateTime in RFC3339 format - `url` string, nullable, required ## Other responses - `401`: Common.APIError - `404`: Common.APIError - `422`: Unprocessible Entity ## Changes - **2026-11-03** `9cd7289ca12b`: 31 warning, 1 info - added the new `DUPLICATE_REJECT_REASON` enum value to the `errors/code` response property for the response status `401` - added the new `DUPLICATE_REJECT_REASON` enum value to the `errors/code` response property for the response status `404` - added the new `DUPLICATE_REJECT_REASON` enum value to the `oneOf[subschema #2: Common.APIError]/errors/code` response property for the response status `422` - added the new `EXTERNAL_STORAGE_ACCESS_FAILED` enum value to the `errors/code` response property for the response status `401` - …28 more [Operation history](https://skmtc.dev/v7labs/apis/darwin/changes/api/v3/teams/:team_slug/reports/jobs/post.md) --- [API](https://skmtc.dev/v7labs/apis/darwin.md) - [All operations](https://skmtc.dev/v7labs/apis/darwin/llms.txt) - [OpenAPI document](https://skmtc.dev/v7labs/apis/darwin/revisions/9cd7289ca12b?raw)