Nightly Pocket Measurement


    1.0.4 • Public • Published


    Build Status

    Astoria is a Node.js 4chan board and thread monitor, useful for programatically keeping track of threads on a particular board, or posts in a particular thread, perfect for writing custom bots and scripts. Astoria makes use of, and aims to follow the guidelines of the 4chan API.

    Installation 🔨

    Add Astoria to your project by installing via npm.

    npm install -S astoria

    Usage ☕️

    Create a new instance of Astoria:

    let Astoria = require('astoria')
    let astoria = new Astoria([options])

    Options 🔧

    The Astoria client can be configured by passing an options object into the constructor with any of the following options.

    Option Type Description Default
    interval number Interval between thread/board polling in seconds. Please be respectful to the server and don't set this below 10 seconds! 30
    updatesOnly boolean If set to true, when listening to a board/thread, only new threads/posts will be sent. Otherwise all current threads/posts will be sent immediately. false
    unsubscribeOnNotFound boolean Whether to automatically stop listening if/when a board/thread returns 404 true
    useHttps boolean Connect to the 4chan API using HTTPS. Only use this if you're using this with an application that also uses HTTPS. false

    Examples 🎈

    • Check the /tv/ board for any new threads that get posted, every 5 minutes, and log out its id.
    let astoria = new Astoria({
        interval: 60 * 5, // 5 mins
        updatesOnly: true // We're only interested in threads posted from now
        .listen((context, threads, err) {
            if (err) {
                return console.log(err)
            threads.forEach(thread => console.log('New thread posted: ',
    • Load a /ck/ thread and stop listening once we've loaded all current replies, logging out their id.
    let astoria = new Astoria()
    let unsubscribe = astoria.board('ck')
        .listen((context, posts, err) {
            if (err) {
                return console.log(err)
            posts.forEach(thread => console.log('Post: ',
            // Stop listening

    API 🔗

    The following members exist on the Astoria client.


    The currently set options on the client. It is generally not recommended to overwrite these, but this property is available if needed.

    .board(boardName): Astoria

    Sets the board to listen to. This can be in a format such as /ck/ or ck. A board is required before the listener can begin.

    Returns the current instance to allow method chaining.


    astoria.board('/tv/') astoria.board('v')

    .thread(threadNumber): Astoria

    Sets the thread to listen to. This can either be in the format 12345678 or '12345678'. Additionally, if you wish to use an existing client which currently has a thread set, you can clear the thread by passing in null.

    Returns the current instance to allow method chaining.


    astoria.thread(55555555) astoria.thread('11115512')

    .listen(function (context, updates, error)): function

    Begin listening to the board (and thread) supplied to the client, based on the current options configuration. The listener creates a snapshot of this configuration, so if any of these values change after this method is called, it won't affect the listener.

    Whenever new data is retrieved from 4chan, the callback will be invoked with the three arguments context, updates and error (described below).

    Returns a function to unsubscribe from the listener. To stop listening to the board/thread, simply invoke the function.



    The board the listener is attached to. e.g. /g/, /an/


    The thread the listener is attached to. e.g. 123512321, undefined


    The options the listener is using. e.g. { interval: 30, useHttps: true, updatesOnly: true, unsubscribeOnNotFound: true }


    An array of new threads or posts. No matter what is being subscribed to, the following properties are available (if present) (with one exception). For example, the first post in a thread will also contain information about the thread, such as reply number, etc. (Table taken from 4chan API)

    attribute value description possible values example value
    no integer Post number 1-9999999999999 9001
    resto integer Reply to 0 (is a thread OP), 1-9999999999999 0
    sticky integer Stickied thread? 0 (no), 1 (yes) 1
    closed integer Closed thread? 0 (no), 1 (yes) 1
    archived integer Archived thread? 0 (no), 1 (yes) 1
    archived_on integer Time when archived UNIX timestamp 1344571233
    now string Date and time MM/DD/YY(Day)HH:MM (:SS on some boards), EST/EDT timezone 08\/08\/12(Wed)01:11
    time integer UNIX timestamp UNIX timestamp 1344570123
    name string Name text moot
    trip string Tripcode text (format: !tripcode!!securetripcode) !Ep8pui8Vw2
    id string ID text (8 characters), Mod, Admin, Manager, Developer, Founder Admin
    capcode string Capcode none, mod, admin, admin_highlight, manager, developer, founder admin
    country string Country code text (2 characters, ISO 3166-1 alpha-2), XX (unknown) XX
    country_name string Country name text Unknown
    sub string Subject text This is a subject
    com string Comment text (includes escaped HTML) This is a comment
    tim integer Renamed filename UNIX timestamp + milliseconds 1344402680740
    filename string Original filename text OPisa
    ext string File extension .jpg, .png, .gif, .pdf, .swf, .webm .jpg
    fsize integer File size 0-10485760 2500
    md5 string File MD5 text (24 character, packed base64 MD5 hash) NOetrLVnES3jUn1x5ZPVAg==
    w integer Image width 1-10000 500
    h integer Image height 1-10000 500
    tn_w integer Thumbnail width 1-250 250
    tn_h integer Thumbnail height 1-250 250
    filedeleted integer File deleted? 0 (no), 1 (yes) 0
    spoiler integer Spoiler image? 0 (no), 1 (yes) 0
    custom_spoiler integer Custom spoilers? 1-99 3
    omitted_posts integer # replies omitted 1-10000 33
    omitted_images integer # image replies omitted 1-10000 21
    replies integer # replies total 0-99999 231
    images integer # images total 0-99999 132
    bumplimit integer Bump limit met? 0 (no), 1 (yes) 0
    imagelimit integer Image limit met? 0 (no), 1 (yes) 1
    capcode_replies array Capcode user replies? array of capcode type and post IDs {"admin":[1234,1267]}
    last_modified integer Time when last modified UNIX timestamp 1344571233
    tag string Thread tag text Loop
    semantic_url string Thread URL slug text daily-programming-thread
    since4pass integer Year 4chan Pass bought 4 digit year (YYYY) 2016

    The exception being when subscribing to threads, each thread will have the following last_replies property on it.

    attribute value description possible values example value
    last_replies array The latest replies on the thread array of post objects (see above) [ { "no": 3214132, "com": "Im too big for this table" } ]


    If an error occurred, this will contain an error object. Errors can include 404, to notify when threads have fallen off the catalog.

    Contributing 🎁

    This project is open to contributions. Please raise an issue before making a contribution. Additionally, please feel free to raise an issue if you find one. For each addition, please add an appropriate test.

    License 💤


    Futher reference 📖

    Please read the 4chan API documentation for further information.


    npm i astoria

    DownloadsWeekly Downloads






    Unpacked Size

    60 kB

    Total Files


    Last publish


    • seqilol