> For the complete documentation index, see [llms.txt](https://cloakedkeys.gitbook.io/ofsc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cloakedkeys.gitbook.io/ofsc/reference/placeholders.md). # Placeholders > ℹ️ This page is copied from the fork's `reference/` folder and is regenerated there. Don't edit it here; run `scripts/sync_reference.py` to refresh it. ## Output template placeholders These are the names you can use in braces in the `file_options.dir_format`, `file_options.file_format` and `metadata` templates, and in text file names (`ofscraper/classes/placeholder.py`). Each column says which template gets the name. Templates are filled with Python's `str.format`, so object values allow attribute or key access. Examples are `{modelObj.name}` and `{args.posts}`. Because `config` is a plain dict, `{config[file_options][date]}` also works. * Profile media (avatar, header) ignore `file_format`. They are saved as `.`. * When `FILE_COUNT_PLACEHOLDER` is on (the default) and `file_format` uses none of `filename`, `only_file_name`, `original_filename` or `media_id`, `_` is added before the extension. This applies to a post with several media, and to a story or highlight. * On Fansly, if the `metadata` template uses none of `save_location`, `root`, `site_name` or `model_id` (or their aliases), the site name is added as a subfolder. This keeps Fansly rows out of an OnlyFans `user_data.db`. * The validators in `ofscraper/prompts/prompt_validators.py` are not called anywhere. They accept only some of these names. | Placeholder | Also | Database path (`metadata`) | Media folders (`dir_format`) | Media file names (`file_format`) | Text files (`--text`) | Description | | --------------------- | -------------------- | -------------------------- | ---------------------------- | -------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{args}` | | | yes | yes | yes | An object: the parsed command-line arguments (an `AutoDotDict`). Use attribute access, for example `{args.posts}`. A missing name gives `None`. | | `{config}` | | | yes | yes | yes | An object: the parsed `config.json` as a dict. Use item syntax, for example `{config[file_options][date]}`. Attribute access does not work. | | `{config_path}` | `{configpath}` | yes | yes | yes | yes | The config home folder, from `common_paths.get_config_home()` (for example `{home_directory}/.config/ofscraper`). It is usually written `{configpath}`, and the default `metadata` path uses it that way. | | `{current_price}` | `{currentprice}` | | yes | yes | yes | `Free` if the creator's final current price is 0, else `Paid`. It is `MODEL_PRICE_PLACEHOLDER` (`Unknown_Price` by default) when the model isn't loaded. | | `{date}` | | | yes | yes | yes | The post's date (`postedAt`, else `createdAt`), formatted with the `file_options.date` config value (arrow tokens, default `MM-DD-YYYY`). | | `{download_type}` | `{downloadtype}` | | yes | yes | | `Protected` for DRM (MPD) media, `Normal` otherwise. | | `{ext}` | | | | yes | yes | The file extension without the dot, for example `mp4` or `jpg`. It is `txt` for text files. | | `{file_name}` | `{filename}` | | yes | yes | yes | The final media file name without the extension. It is the name from the media URL, or the media id if there is none. Videos get `_` appended. The name is cleaned and spaces are replaced by `space_replacer`. For text files it is the sanitised, truncated post text. It is usually written `{filename}`, and the default `file_format` is `{filename}.{ext}`. | | `{first_letter}` | `{firstletter}` | yes | yes | yes | yes | The first letter of the creator's username, upper-cased, for example `A`. | | `{label}` | | | yes | yes | yes | The post's label name (on Fansly, the wall name), or the string `None` when it has no label. Only posts found through the Labels area carry one. Files go into a folder per label only when `dir_format` uses `{label}`. With the default `dir_format`, labelled posts are saved with the timeline and the labels are recorded only in the `labels` table. A post in both the timeline and a label is downloaded once; with `{label}` in `dir_format`, its folder depends on which area returned it first. A file that an earlier run already downloaded (for example from the timeline) stays where it is: it isn't moved, or downloaded again, into the label folder (unless `--force-all` re-downloads it). | | `{media_id}` | `{mediaid}` | | yes | yes | | The id of the media item. Including it (or a filename field) in `file_format` stops the automatic `_` suffix. | | `{media_type}` | `{mediatype}` | | yes | yes | yes | The capitalised media kind: `Images`, `Videos` (gifs count as `Videos`), `Audios`, `Forced_skipped`, or `Text` for text files. It is usually written `{mediatype}`. | | `{modelObj}` | | | yes | yes | yes | An object: the creator's model (`ofscraper/classes/of/models.py`) from the model manager. Use attribute access, for example `{modelObj.name}`, `{modelObj.id}` or `{modelObj.final_current_price}`. It is `None` if the creator isn't loaded, so attribute access then fails. | | `{model_id}` | `{modelid}` | yes | yes | yes | yes | The creator's numeric account id. OnlyFans ids are short, and Fansly ids are 18-digit snowflakes. The default `metadata` path is `{configpath}/{profile}/.data/{model_id}`. | | `{model_username}` | `{modelusername}` | yes | yes | yes | yes | The creator's username. The media and post objects lower-case it for dir and file names. | | `{my_id}` | `{myid}` | yes | yes | yes | yes | The numeric id of the logged-in account. It is `anon` in anonymous mode. | | `{my_username}` | `{myusername}` | yes | yes | yes | yes | The username of the logged-in account. It is `anon` in anonymous mode. | | `{only_file_name}` | `{onlyfilename}` | | yes | yes | yes | Like `{file_name}`, but without the video quality suffix. For text files it is the sanitised post text. | | `{only_filename}` | `{onlyfilename}` | | yes | yes | yes | The same value as `{only_file_name}`. | | `{original_filename}` | `{originalfilename}` | | yes | yes | yes | The file name taken from the media URL (the raw media filename, `None` when the media has no URL). For text files it is the sanitised post text. | | `{post_id}` | `{postid}` | | yes | yes | yes | The id of the post or message the media belongs to. For text files, it is the post's own id. | | `{profile}` | | yes | yes | yes | yes | The name of the active profile, for example `main_profile`. | | `{promo_price}` | `{promoprice}` | | yes | yes | yes | `Free` or `Paid`, from the creator's final promo price, or `MODEL_PRICE_PLACEHOLDER`. | | `{quality}` | | | yes | yes | yes | The selected video quality, such as `1080`, `720`, `240` or `source`. Non-videos and text files are `source` (`QUALITY_UNKNOWN_DEFAULT` when the quality is unknown). | | `{regular_price}` | `{regularprice}` | | yes | yes | yes | `Free` or `Paid`, from the creator's final regular price, or `MODEL_PRICE_PLACEHOLDER`. | | `{renewal_price}` | `{renewalprice}` | | yes | yes | yes | `Free` or `Paid`, from the creator's final renewal price, or `MODEL_PRICE_PLACEHOLDER`. | | `{response_type}` | `{responsetype}` | | yes | yes | yes | The display name of the content area, from the `responsetype` config map. The defaults are Posts, Messages, Archived, Stories, Profile and Streams. Timeline and pinned map to Posts, paid maps to Messages, and highlights map to Stories. Archived posts use the configured Archived name. It is usually written `{responsetype}`. | | `{root}` | | yes | yes | yes | yes | A `pathlib.Path` of `{save_location}`: the media root, with the Fansly subfolder included. | | `{save_location}` | `{savelocation}` | yes | yes | yes | yes | The configured save location. On Fansly runs it is `/Fansly`. It has the same value as `{root}`, but as the configured string. | | `{site_name}` | `{sitename}` | yes | yes | yes | yes | The name of the site being scraped, from `sites.site_name()`. On Fansly runs this is the Fansly name. It is usually written `{sitename}`. | | `{text}` | | | yes | yes | yes | For media: the post text, cleaned and truncated to `textlength`. It falls back to the file name, the date, or the media id. For text files: the sanitised, truncated post text. | | `{user_name}` | `{username}` | | yes | yes | yes | The creator's username, the same as `{model_username}`. Its alias `{username}` also works. | | `{username}` | | yes | | | | The creator's username. In `dir_format`, `file_format` and text files it is also the underscore-free alias of `{user_name}`, with the same value. | | `{value}` | | | yes | yes | yes | `Free` or `Paid`, from the post's price. A price of 0 means `Free`. | The underscore-free form is added for every name with an underscore (`add_no_underline`). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://cloakedkeys.gitbook.io/ofsc/reference/placeholders.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.