Scraper Operations - Stash Tools & Scrapers

Operations for scraping metadata from external sources. Bases: StashClientProtocol Mixin for scraper-related client methods.

Functions

list_scrapers

list_scrapers(
    types: list[ScrapeContentType],
) -> list[Scraper]

List available scrapers filtered by content types. Parameters:

Name	Type	Description	Default
`types`	`list[ScrapeContentType]`	List of content types to filter scrapers by (GALLERY, IMAGE, MOVIE, GROUP, PERFORMER, SCENE)	required

Returns:

Type	Description
`list[Scraper]`	List of Scraper objects matching the requested types

Examples: List all scene scrapers:

scrapers = await client.list_scrapers([ScrapeContentType.SCENE])
for scraper in scrapers:
    print(f"Scene scraper: {scraper.name}")

List multiple scraper types:

from stash_graphql_client.types import ScrapeContentType
scrapers = await client.list_scrapers([
    ScrapeContentType.SCENE,
    ScrapeContentType.PERFORMER
])

Check scraper capabilities:

scrapers = await client.list_scrapers([ScrapeContentType.SCENE])
for scraper in scrapers:
    if scraper.scene:
        print(f"{scraper.name} supports: {scraper.scene.supported_scrapes}")
        print(f"URLs: {scraper.scene.urls}")

scrape_single_scene

scrape_single_scene(
    source: ScraperSourceInput,
    input: ScrapeSingleSceneInput,
) -> list[ScrapedScene]

Scrape for a single scene. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleSceneInput`	Scene scraping input (query, scene_id, or scene_input)	required

Returns:

Type	Description
`list[ScrapedScene]`	List of ScrapedScene objects

Examples: Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleSceneInput(query="scene title")
scenes = await client.scrape_single_scene(source, input)

Scrape by scene ID (using fingerprints):

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleSceneInput(scene_id="scene-456")
scenes = await client.scrape_single_scene(source, input)

Scrape from StashBox:

source = ScraperSourceInput(stash_box_endpoint="https://stashdb.org")
input = ScrapeSingleSceneInput(query="scene title")
scenes = await client.scrape_single_scene(source, input)

scrape_multi_scenes

scrape_multi_scenes(
    source: ScraperSourceInput,
    input: ScrapeMultiScenesInput,
) -> list[list[ScrapedScene]]

Scrape for multiple scenes. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeMultiScenesInput`	Multi-scene scraping input (scene_ids)	required

Returns:

Type	Description
`list[list[ScrapedScene]]`	List of lists of ScrapedScene objects (one list per input scene)

Examples: Scrape multiple scenes:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeMultiScenesInput(scene_ids=["1", "2", "3"])
results = await client.scrape_multi_scenes(source, input)
for i, scenes in enumerate(results):
    print(f"Scene {i+1}: {len(scenes)} matches found")

scrape_single_studio

scrape_single_studio(
    source: ScraperSourceInput,
    input: ScrapeSingleStudioInput,
) -> list[ScrapedStudio]

Scrape for a single studio. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleStudioInput`	Studio scraping input (query - can be name or Stash ID)	required

Returns:

Type	Description
`list[ScrapedStudio]`	List of ScrapedStudio objects

Examples: Scrape studio by name:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleStudioInput(query="Studio Name")
studios = await client.scrape_single_studio(source, input)

scrape_single_tag

scrape_single_tag(
    source: ScraperSourceInput, input: ScrapeSingleTagInput
) -> list[ScrapedTag]

Scrape for a single tag. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleTagInput`	Tag scraping input (query - can be name or Stash ID)	required

Returns:

Type	Description
`list[ScrapedTag]`	List of ScrapedTag objects

Examples: Scrape tag by name:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleTagInput(query="Tag Name")
tags = await client.scrape_single_tag(source, input)

Scrape from StashBox:

source = ScraperSourceInput(stash_box_endpoint="https://stashdb.org")
input = ScrapeSingleTagInput(query="Tag Name")
tags = await client.scrape_single_tag(source, input)

scrape_single_performer

scrape_single_performer(
    source: ScraperSourceInput,
    input: ScrapeSinglePerformerInput,
) -> list[ScrapedPerformer]

Scrape for a single performer. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSinglePerformerInput`	Performer scraping input (query, performer_id, or performer_input)	required

Returns:

Type	Description
`list[ScrapedPerformer]`	List of ScrapedPerformer objects

Examples: Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSinglePerformerInput(query="Performer Name")
performers = await client.scrape_single_performer(source, input)

Scrape by performer ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSinglePerformerInput(performer_id="123")
performers = await client.scrape_single_performer(source, input)

scrape_multi_performers

scrape_multi_performers(
    source: ScraperSourceInput,
    input: ScrapeMultiPerformersInput,
) -> list[list[ScrapedPerformer]]

Scrape for multiple performers. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeMultiPerformersInput`	Multi-performer scraping input (performer_ids)	required

Returns:

Type	Description
`list[list[ScrapedPerformer]]`	List of lists of ScrapedPerformer objects (one list per input performer)

Examples: Scrape multiple performers:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeMultiPerformersInput(performer_ids=["1", "2", "3"])
results = await client.scrape_multi_performers(source, input)
for i, performers in enumerate(results):
    print(f"Performer {i+1}: {len(performers)} matches found")

scrape_single_gallery

scrape_single_gallery(
    source: ScraperSourceInput,
    input: ScrapeSingleGalleryInput,
) -> list[ScrapedGallery]

Scrape for a single gallery. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleGalleryInput`	Gallery scraping input (query, gallery_id, or gallery_input)	required

Returns:

Type	Description
`list[ScrapedGallery]`	List of ScrapedGallery objects

Examples: Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGalleryInput(query="gallery title")
galleries = await client.scrape_single_gallery(source, input)

Scrape by gallery ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGalleryInput(gallery_id="456")
galleries = await client.scrape_single_gallery(source, input)

scrape_single_movie

scrape_single_movie(
    source: ScraperSourceInput,
    input: ScrapeSingleMovieInput,
) -> list[ScrapedMovie]

Scrape for a single movie. Deprecated: Use scrape_single_group instead. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleMovieInput`	Movie scraping input (query, movie_id, or movie_input)	required

Returns:

Type	Description
`list[ScrapedMovie]`	List of ScrapedMovie objects

Examples: Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleMovieInput(query="movie title")
movies = await client.scrape_single_movie(source, input)

scrape_single_group

scrape_single_group(
    source: ScraperSourceInput,
    input: ScrapeSingleGroupInput,
) -> list[ScrapedGroup]

Scrape for a single group. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleGroupInput`	Group scraping input (query, group_id, or group_input)	required

Returns:

Type	Description
`list[ScrapedGroup]`	List of ScrapedGroup objects

Examples: Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGroupInput(query="group title")
groups = await client.scrape_single_group(source, input)

Scrape by group ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleGroupInput(group_id="789")
groups = await client.scrape_single_group(source, input)

scrape_single_image

scrape_single_image(
    source: ScraperSourceInput,
    input: ScrapeSingleImageInput,
) -> list[ScrapedImage]

Scrape for a single image. Parameters:

Name	Type	Description	Default
`source`	`ScraperSourceInput`	Scraper source (scraper_id or stash_box_endpoint)	required
`input`	`ScrapeSingleImageInput`	Image scraping input (query, image_id, or image_input)	required

Returns:

Type	Description
`list[ScrapedImage]`	List of ScrapedImage objects

Examples: Scrape by query string:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleImageInput(query="image title")
images = await client.scrape_single_image(source, input)

Scrape by image ID:

source = ScraperSourceInput(scraper_id="scraper-123")
input = ScrapeSingleImageInput(image_id="101")
images = await client.scrape_single_image(source, input)

scrape_url

scrape_url(url: str, ty: ScrapeContentType) -> Any

Scrape content based on a URL. Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape	required
`ty`	`ScrapeContentType`	Type of content to scrape (GALLERY, IMAGE, MOVIE, GROUP, PERFORMER, SCENE)	required

Returns:

Type	Description
`Any`	ScrapedContent union type (could be any scraped type based on ty parameter)

Returns ScrapedStudio, ScrapedTag, ScrapedScene, ScrapedGallery, ScrapedImage, ScrapedMovie, ScrapedGroup, or ScrapedPerformer depending on the content type.

Examples: Scrape a scene from URL:

from stash_graphql_client.types import ScrapeContentType
content = await client.scrape_url(
    "https://example.com/scene/123",
    ScrapeContentType.SCENE
)
if content:
    print(f"Scraped scene: {content.title}")

Scrape a performer from URL:

content = await client.scrape_url(
    "https://example.com/performer/456",
    ScrapeContentType.PERFORMER
)
if content:
    print(f"Scraped performer: {content.name}")

scrape_performer_url

scrape_performer_url(url: str) -> ScrapedPerformer | None

Scrape a complete performer record based on a URL. Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape performer from	required

Returns:

Type	Description
`ScrapedPerformer \| None`	ScrapedPerformer object if successful, None otherwise

Examples: Scrape performer from URL:

performer = await client.scrape_performer_url("https://example.com/performer/123")
if performer:
    print(f"Name: {performer.name}")
    print(f"Birthdate: {performer.birthdate}")
    print(f"Gender: {performer.gender}")

scrape_scene_url

scrape_scene_url(url: str) -> ScrapedScene | None

Scrape a complete scene record based on a URL. Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape scene from	required

Returns:

Type	Description
`ScrapedScene \| None`	ScrapedScene object if successful, None otherwise

Examples: Scrape scene from URL:

scene = await client.scrape_scene_url("https://example.com/scene/123")
if scene:
    print(f"Title: {scene.title}")
    print(f"Date: {scene.date}")
    print(f"Studio: {scene.studio.name if scene.studio else 'Unknown'}")

scrape_gallery_url

scrape_gallery_url(url: str) -> ScrapedGallery | None

Scrape a complete gallery record based on a URL. Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape gallery from	required

Returns:

Type	Description
`ScrapedGallery \| None`	ScrapedGallery object if successful, None otherwise

Examples: Scrape gallery from URL:

gallery = await client.scrape_gallery_url("https://example.com/gallery/123")
if gallery:
    print(f"Title: {gallery.title}")
    print(f"Date: {gallery.date}")
    print(f"Performers: {len(gallery.performers or [])}")

scrape_image_url

scrape_image_url(url: str) -> ScrapedImage | None

Scrape a complete image record based on a URL. Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape image from	required

Returns:

Type	Description
`ScrapedImage \| None`	ScrapedImage object if successful, None otherwise

Examples: Scrape image from URL:

image = await client.scrape_image_url("https://example.com/image/123")
if image:
    print(f"Title: {image.title}")
    print(f"Date: {image.date}")
    print(f"Tags: {len(image.tags or [])}")

scrape_movie_url

scrape_movie_url(url: str) -> ScrapedMovie | None

Scrape a complete movie record based on a URL. Deprecated: Use scrape_group_url instead. Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape movie from	required

Returns:

Type	Description
`ScrapedMovie \| None`	ScrapedMovie object if successful, None otherwise

Examples: Scrape movie from URL:

movie = await client.scrape_movie_url("https://example.com/movie/123")
if movie:
    print(f"Name: {movie.name}")
    print(f"Date: {movie.date}")
    print(f"Duration: {movie.duration}")

scrape_group_url

scrape_group_url(url: str) -> ScrapedGroup | None

Scrape a complete group record based on a URL. Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to scrape group from	required

Returns:

Type	Description
`ScrapedGroup \| None`	ScrapedGroup object if successful, None otherwise

Examples: Scrape group from URL:

group = await client.scrape_group_url("https://example.com/group/123")
if group:
    print(f"Name: {group.name}")
    print(f"Date: {group.date}")
    print(f"Synopsis: {group.synopsis}")

reload_scrapers

reload_scrapers() -> bool

Reload all scrapers from configuration. Returns:

Type	Description
`bool`	True if successful, False otherwise

Examples: Reload scrapers after configuration change:

success = await client.reload_scrapers()
if success:
    print("Scrapers reloaded successfully")
    # List scrapers to verify
    scrapers = await client.list_scrapers([ScrapeContentType.SCENE])
    print(f"Found {len(scrapers)} scene scrapers")

submit_stashbox_fingerprints

submit_stashbox_fingerprints(
    input_data: StashBoxFingerprintSubmissionInput
    | dict[str, Any],
) -> bool

Submit fingerprints to StashBox. Parameters:

Name	Type	Description	Default
`input_data`	`StashBoxFingerprintSubmissionInput \| dict[str, Any]`	StashBoxFingerprintSubmissionInput object or dictionary	required

Returns:

Type	Description
`bool`	True if successful

submit_stashbox_scene_draft

submit_stashbox_scene_draft(
    input_data: StashBoxDraftSubmissionInput
    | dict[str, Any],
) -> str

Submit scene draft to StashBox. Parameters:

Name	Type	Description	Default
`input_data`	`StashBoxDraftSubmissionInput \| dict[str, Any]`	StashBoxDraftSubmissionInput object or dictionary	required

Returns:

Type	Description
`str`	Draft ID

submit_stashbox_performer_draft

submit_stashbox_performer_draft(
    input_data: StashBoxDraftSubmissionInput
    | dict[str, Any],
) -> str

Submit performer draft to StashBox. Parameters:

Name	Type	Description	Default
`input_data`	`StashBoxDraftSubmissionInput \| dict[str, Any]`	StashBoxDraftSubmissionInput object or dictionary	required

Returns:

Type	Description
`str`	Draft ID

stashbox_batch_performer_tag

stashbox_batch_performer_tag(
    input_data: dict[str, Any],
) -> str

Batch tag performers from StashBox. Parameters:

Name	Type	Description	Default
`input_data`	`dict[str, Any]`	Batch performer tag input dictionary	required

Returns:

Type	Description
`str`	Job ID

stashbox_batch_studio_tag

stashbox_batch_studio_tag(
    input_data: dict[str, Any],
) -> str

Batch tag studios from StashBox. Parameters:

Name	Type	Description	Default
`input_data`	`dict[str, Any]`	Batch studio tag input dictionary	required

Returns:

Type	Description
`str`	Job ID

stashbox_batch_tag_tag

stashbox_batch_tag_tag(input_data: dict[str, Any]) -> str

Batch tag tags from StashBox. Parameters:

Name	Type	Description	Default
`input_data`	`dict[str, Any]`	Batch tag input dictionary (StashBoxBatchTagInput)	required

Returns:

Type	Description
`str`	Job ID

​Functions

​list_scrapers

​scrape_single_scene

​scrape_multi_scenes

​scrape_single_studio

​scrape_single_tag

​scrape_single_performer

​scrape_multi_performers

​scrape_single_gallery

​scrape_single_movie

​scrape_single_group

​scrape_single_image

​scrape_url

​scrape_performer_url

​scrape_scene_url

​scrape_gallery_url

​scrape_image_url

​scrape_movie_url

​scrape_group_url

​reload_scrapers

​submit_stashbox_fingerprints

​submit_stashbox_scene_draft

​submit_stashbox_performer_draft

​stashbox_batch_performer_tag

​stashbox_batch_studio_tag

​stashbox_batch_tag_tag

Functions

list_scrapers

scrape_single_scene

scrape_multi_scenes

scrape_single_studio

scrape_single_tag

scrape_single_performer

scrape_multi_performers

scrape_single_gallery

scrape_single_movie

scrape_single_group

scrape_single_image

scrape_url

scrape_performer_url

scrape_scene_url

scrape_gallery_url

scrape_image_url

scrape_movie_url

scrape_group_url

reload_scrapers

submit_stashbox_fingerprints

submit_stashbox_scene_draft

submit_stashbox_performer_draft

stashbox_batch_performer_tag

stashbox_batch_studio_tag

stashbox_batch_tag_tag