# Fetching a list of Stories This endpoint returns structured Story objects. As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array and will be indexed by ID in the stories top-level JSON key. Please see our Response Format section for more information. Endpoint: GET /stories Version: 1.0.0 ## Query parameters: - `active_between` (string) Filter for tasks that have a start or due date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01. - `all_on_account` (boolean) If you are a reports viewer or administrator, you can retrieve all stories on an account. - `archived` (string) Include, filter for, _or_ exclude archived tasks (e.g. GET https://api.mavenlink.com/api/v1/stories?archived=exclude). Valid values: include, only, exclude. - `assigned_to_current_user` (boolean) If set to true, includes tasks that are assigned to the user making the request. - `by_any_tag` (string) Include tasks with at least 1 of the specified tags. Give multiple tags in a comma-separated list (e.g. GET /api/v1/stories.json?by_tag_name=design,product management,writing). Tags (and therefore valid values for tags) are defined by users. - `by_custom_choice_value` (string) Filter by a custom field choice value, represented as a string with the custom field ID, followed by a colon, and then comma-separated custom field choice value IDs. The custom field choice value can also be the word blank. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - custom_field_ID:choice_value_ID - custom_field_ID:choice_value_1_ID,choice_value_2_ID - custom_field_ID:blank - (custom_field_1_ID:choice_value_1_ID,choice_value_2_ID):(custom_field_2_ID:choice_value_3_ID). - `by_custom_currency_value` (string) Filter by a custom field currency value, represented as a string with the custom field ID, followed by a colon, and then the currency value. Optionally, the currency ISO code can be supplied as well, separated from the currency value by another colon. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:200.2:USD):(2:100). - `by_custom_date_field` (string) Filter for tasks with custom fields that have a date value within a specified range. Specify the custom field ID and date range in a colon-separated string, with dates in a YYYY-MM-DD format. For example, GET /api/v1/stories.json?by_custom_date_field=18290:2018-05-02:2018-06-01. Give multiple custom fields with date values in a semicolon-separated list (e.g. GET /api/v1/stories.json?by_custom_date_field=18290:2018-05-02:2018-06-01;18291:2018-06-15:2018-08-15). - `by_custom_date_value` (string) Filter by a custom field date value, represented as a string with the custom field ID, followed by a colon, the starting date, another colon, and then the ending date. You can provide both a starting date and ending date, or provide just one. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:2014-12-05:2014-12-25):(2:2014-12-05). - `by_custom_number_value` (string) Filter by a custom field number value, represented as a string with the custom field ID, followed by a colon, and then the number value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:200):(2:101). - `by_custom_text_value` (string) Filter by a custom field text value, represented as a string with the custom field ID, followed by a colon, and then the text value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:something):(2:else). - `by_status` (string) Filter by task status. Provide a comma-separated list of task status names. - `by_subtask_count` (integer) Filters for parent tasks with the specified number of subtasks. - `by_tag_name` (string) Include tasks with the exact tags specified. Give multiple tags in a comma-separated list (e.g. GET /api/v1/stories.json?by_tag_name=development,data analysis). Tags (and therefore valid values for tags) are defined by users. - `by_workspace_group` (string) Filter for tasks in projects that belong to a Project Group (ID). Give multiple project group IDs in a comma-separated list. - `completed` (boolean) Filter for only completed tasks. If false, no filtering is applied. - `completed_between` (string) Filter for tasks that were completed within the specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01. - `created_after` (string) Filter for records created after a specified datetime. The datetime must be in ISO 8601 format. - `created_before` (string) Filter for records created before a specified datetime. The datetime must be in ISO 8601 format. - `creators` (string) Filter for tasks created by the specified user (ID). Give multiple user IDs in a comma-separated list (e.g. GET https://api.mavenlink.com/api/v1/stories?creators=1,2,3). - `due_after` (string) Filter for tasks that are due after the specified date. The date must be in ISO 8601 format. - `due_before` (string) Filter for tasks that are due before the specified date. The date must be in ISO 8601 format. - `due_between` (string) Filter for tasks with a due date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01. - `due_on` (string) Filter for tasks that are due on the specified date. The date must be in ISO 8601 format. - `exclude_workspace_title_from_search` (boolean) If set to true, excludes tasks in projects with a title that matches searched text. - `external_reference_external_message` (string) Filter the objects based on the external message of their associated external references. This is an exact match. - `external_reference_external_status` (string) Filter by the status of the external object in the external system. - `external_reference_service_model` (string) Filter by the type of the external object this external reference belongs to. - `external_reference_service_model_ref` (integer) Filter by the id of the external object this external reference belongs to. - `external_reference_service_model_refs` (string) Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs. - `external_reference_service_name` (string) Filter by the name of the provider for integration. - `external_reference_status` (string) Filter by the status of the integration, this can be successful or fail. - `has_external_references` (boolean) Filter by whether or not the object has external references. - `has_value_for_custom_field_ids` (string) Filter by the presence of a custom field value for the specified comma-separated custom field ID(s). - `include` (string) Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2. - ancestors (Story) - Retrieves all of the tasks that the task is nested under (parents and top-level tasks). The response will include ancestor_ids, which references the data in the stories top-level key. - assigned_role (Role) - Retrieves the authenticated user’s assigned role for the task. The response will include assigned_role_id, which references the data in the roles top-level key. - assignees (User) - Retrieves all users assigned to the task, excluding unnamed resources. The response will include assignee_ids, which references the data in the users top-level key. - attachments (Attachments::PostAttachment) - Retrieves all attachments in the task's posts. The response will include attachment_ids, which references the data in the attachments top-level key. Must be used with the only parameter. - creator (User) - Retrieves the user who created the task. The response will include creator_id, which references the data in the users top-level key. - current_assignments (Assignment) - Retrieves all assignments for the task. The response will include current_assignment_ids, which references the data in the assignments top-level key. - custom_field_values (CustomFieldValue) - Retrieves the task’s custom field values. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key. - descendants (Story) - Retrieves all of the subtasks nested under this top-level task. The response will include descendant_ids, which references the data in the stories top-level key. - external_references (ExternalReference) - Includes references to external integrations for this object. - followers (User) - Retrieves all users following the task. The response will include follower_ids, which references the data in the users top-level key. - google_documents (GoogleDocument) - Retrieves all Google documents for the task. The response will include google_document_ids, which references the data in the google_documents top-level key. Must be used with the only parameter. - parent (Story) - Retrieves the parent task that this subtask is nested directly under. The response will include parent_id, which references the data in the stories top-level key. - potential_workspace_resources (WorkspaceResource) - Retrieves the project's named resources who are not assigned to the task. The response will include potential_workspace_resource_ids, which references the data in the workspace_resources top-level key. Must be used with the only parameter. - potential_workspace_resources_with_unnamed (WorkspaceResource) - Retrieves all of the project's resources (named and unnamed) who are not assigned to the task. The response will include potential_workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key. Must be used with the only parameter. - replies (Post) - Retrieves all task posts, except for the first one. The response will include reply_ids, which references the data in the posts top-level key. Must be used with the only parameter. - root (Story) - Retrieves the top-level task that this subtask is nested under. The response will include root_id, which references the data in the stories top-level key. - source_dependencies (StoryDependency) - Retrieves all tasks that this task is dependent on. The response will include source_dependency_ids, which references the data in the story_dependencies top-level key. - story_state_changes (StoryStateChange) - Retrieves all status changes the task has gone through. The response will include story_state_change_ids, which references the data in the story_state_changes top-level key. Must be used with the only parameter. - story_tasks (StoryTask) - Retrieves all checklist items for the task. The response will include story_task_ids, which references the data in the story_tasks top-level key. - sub_stories (Story) - Retrieves all direct subtasks of the task. This does not include the subtasks of its direct subtasks. The response will include sub_story_ids, which references the data in the stories top-level key. - tags (ActsAsTaggableOn::Tag) - Retrieves all tags for the task. The response will include tag_ids, which references the data in the tags top-level key. - target_dependencies (StoryDependency) - Retrieves all tasks that are dependent on this task. The response will include target_dependency_ids, which references the data in the story_dependencies top-level key. - workspace (Workspace) - Retrieves the project the task is in. The response will include workspace_id, which references the data in the workspaces top-level key. - workspace_resources (WorkspaceResource) - Retrieves the named resources who are assigned to the task. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key. - workspace_resources_with_unnamed (WorkspaceResource) - Retrieves all of the resources (named and unnamed) assigned to the task. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key. - `not_assigned_to_resource` (integer) Filter for tasks not assigned to the specified resource (ID). - `not_assigned_to_user` (integer) Filter for tasks not assigned to the specified user (ID). - `only` (string) Allows you to request one or more resources directly by ID. Multiple IDs can be supplied in a comma separated list, like GET /api/v1/workspaces.json?only=5,6,7. - `only_archived` (boolean) If set to true, filters for archived tasks. - `only_deleted` (boolean) If set to true, filters for deleted tasks. - `only_todos` (boolean) If set to true, filters for only To Dos. - `optional_fields` (array) Allows you to request one or more optional fields as an array. Enum: "read_only", "can_edit", "can_post", "archived_editable", "is_time_trackable_type", "has_out_of_bounds_sads", "can_align_time", "formatted_description", "parsed_description", "render_description_markdown" - `order` (string) Supply order with the name of a valid sort field for the endpoint and a direction. Valid values: created_at:asc, created_at:desc, due_date:asc, due_date:desc, importance, parent_and_position, position, priority_level:asc, priority_level:desc, start_date:asc, start_date:desc, updated_at:asc, and updated_at:desc. - `page` (integer) - `parents_only` (boolean) Filter for top-level tasks. This does not include subtasks that have other subtasks nested under them. - `per_page` (integer) - `priority` (string) Filter for tasks with the specified priorities. Give multiple priorities in a comma-separated list (GET https://api.mavenlink.com/api/v1/stories?priority=critical,high). Valid values: critical, high, normal, low. - `search` (string) - `show_archived` (boolean) If set to true, includes archived tasks in the response. - `show_deleted` (boolean) If set to true, includes deleted tasks. - `show_from_archived_workspaces` (boolean) If set to true, filters for tasks in archived projects. - `show_todos` (boolean) If set to true, includes To Dos in the response. - `starting_between` (string) Filter for tasks with a start date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01. - `story_type` (string) Include tasks of the specified type. Valid values: task, milestone, deliverable, issue. - `story_types` (string) Filter for tasks of the specified type(s). Give multiple task types in a comma-separated list. - `time_trackable_on_workspace_id` (integer) Filter for tasks that time can be tracked against in the specified project (ID). - `uncompleted` (boolean) Filter for only incomplete tasks. If false, no filtering is applied. - `updated_after` (string) Filter for records updated after a specified datetime. The datetime must be in ISO 8601 format. - `updated_before` (string) Filter for records updated before a specified datetime. The datetime must be in ISO 8601 format. - `with_ancestry_depth` (integer) Include subtasks that are nested at the specified level from the top-level task (e.g. GET /api/v1/stories.json?with_ancestry_depth=3). The top-level task is considered to be at the 0 level. Subtasks can be nested up to 4 levels from the top-level task. - `with_assignees` (string) Filter for tasks assigned to the specified users. Give multiple user IDs in a comma-separated list (e.g. GET https://api.mavenlink.com/api/v1/stories?with_assignees=1,2,3). In addition to user IDs, you can also pass unassigned and unnamed. These can be included in a comma-separated list (e.g. GET https://api.mavenlink.com/api/v1/stories?with_assignees=1,2,3,unassigned,unnamed). unassigned returns tasks that are not assigned to any users. unnamed returns tasks assigned to unnamed resources. - `with_followers` (string) Filter for tasks with the specified followers. Give multiple user IDs in a comma-separated list. - `with_parent_id` (integer) Filter for subtasks that are directly nested under the specified task (ID). - `with_projects` (string) Include tasks in the specified projects. Give multiple project IDs in a comma-separated list. - `with_root_id` (integer) Filter for subtasks that are nested at any level under the specified task (ID). - `with_start_or_due_date` (string) Filter for tasks with start or due dates. - `without_external_reference_service_name` (string) Exclude by the existence of an external reference with the specified service name. - `without_past_completed` (boolean) If set to true, filters for tasks that haven't previously been marked as completed. - `workspace_id` (integer) Filter for tasks from the specified project (ID). ## Response 200 fields (application/json): - `count` (integer) - `meta` (object) - `meta.count` (integer) - `meta.page_count` (integer) - `meta.page_number` (integer) - `meta.page_size` (integer) - `results` (array) - `results.key` (string) - `results.id` (string) - `stories` (object) - `external_references` (object) - `workspace_resources` (object) - `workspaces` (object) - `users` (object) - `assignments` (object) - `story_tasks` (object) - `tags` (object) - `story_state_changes` (object) - `posts` (object) - `attachments` (object) - `story_dependencies` (object) - `custom_field_values` (object) - `roles` (object) ## Response 400 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string)