post
/users/@me/harvest/filteredRequest filtered data harvest
Requests a data harvest with the same optional scope and date-range filters offered by the bulk-delete endpoint. Settings, memberships, and other non-message data are always included; the filter only constrains which messages end up in the archive. Returns harvest ID and status.
request_filtered_data_harvest
Request body
application/json
json
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": [
"selected",
"inaccessible_only"
],
"x-enumNames": [
"Selected",
"Inaccessible Only"
],
"x-enumDescriptions": [
"Delete messages matching the explicit include_* toggles and excluded_guild_ids.",
"Delete only messages in places the caller no longer has access to (guilds left or removed from, group DMs left). Direct messages are not affected by this mode since the caller can always reopen them."
],
"description": "Which set of contexts the deletion targets"
},
"include_dms": {
"type": "boolean",
"description": "Include 1:1 direct messages the caller still has open."
},
"include_dms_closed": {
"type": "boolean",
"description": "Include 1:1 direct messages the caller has previously closed. Independent of include_dms — set include_dms=false and include_dms_closed=true to target closed DMs only."
},
"include_group_dms": {
"type": "boolean",
"description": "Include group DMs the caller is still a member of."
},
"include_guilds": {
"type": "boolean",
"description": "Include text channels in guilds the caller is a member of."
},
"guild_filter_mode": {
"type": "string",
"enum": [
"exclude",
"include_only"
],
"x-enumNames": [
"Exclude",
"Include Only"
],
"x-enumDescriptions": [
"Apply to every guild except those listed in excluded_guild_ids.",
"Apply only to the guilds listed in included_guild_ids; all other guilds are left untouched."
],
"description": "How the guild filter list is interpreted when include_guilds is true."
},
"excluded_guild_ids": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SnowflakeType"
},
"maxItems": 500,
"description": "Guild IDs to leave untouched. Used when include_guilds is true, guild_filter_mode is exclude, and scope is selected."
},
"included_guild_ids": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SnowflakeType"
},
"maxItems": 500,
"description": "The only guild IDs to apply this operation to. Used when include_guilds is true, guild_filter_mode is include_only, and scope is selected."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Inclusive ISO8601 lower bound for message timestamps. Null/omitted means unbounded in the past."
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Exclusive ISO8601 upper bound for message timestamps. Null/omitted means unbounded in the future."
}
}
}Responses
200
Success
json
{
"type": "object",
"properties": {
"harvest_id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"description": "Unique identifier for the harvest request"
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
],
"x-enumNames": [
"pending",
"processing",
"completed",
"failed"
],
"x-enumDescriptions": [
"The harvest job is waiting to be processed",
"The harvest job is currently being processed",
"The harvest job has finished successfully",
"The harvest job encountered an error and could not complete"
],
"description": "Current status of the harvest request"
},
"created_at": {
"type": "string",
"description": "ISO 8601 timestamp when the harvest request was created"
}
},
"required": [
"harvest_id",
"status",
"created_at"
]
}400
Bad Request - The request was malformed or contained invalid data
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}401
Unauthorized - Authentication is required or the token is invalid
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}403
Forbidden - You do not have permission to perform this action
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}429
Too Many Requests - You are being rate limited
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RATE_LIMITED"
]
},
"message": {
"type": "string"
},
"retry_after": {
"type": "number",
"description": "Seconds to wait before retrying"
},
"global": {
"type": "boolean",
"description": "Whether this is a global rate limit"
}
},
"required": [
"code",
"message",
"retry_after"
]
}500
Internal Server Error - An unexpected error occurred
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}