Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.
 

POST /labs/1/tweets/stream/filter/rules (create)

Creates filter rules. To create one or more rules, submit an add payload as an array of rules and operators.



Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

Rate limit 450 requests per 15-minute window

Learn more about rate limits.



Query parameters

Name Type Description
dry_run
 Optional 
boolean Set to true to test a the syntax of your rule without submitting it. This is useful if you want to check the syntax of a rule before removing one or more of your existing rules.



JSON body parameters

Name Type Description
add
 Required 
array Specifies the operation you want to perform on the rules.
add.value
 Required 
string The rule text. Up to 512 characters are allowed.
add.tag
 Optional 
string The tag label. This is a free-form text you can use to identify the rules that matched a specific Tweet in the streaming response. Tags can be the same across rules.



Examples

  • Add rules
  • Validate rules
curl -X POST 'https://api.twitter.com/labs/1/tweets/stream/filter/rules' \
-H "Content-type: application/json" \
-H "Authorization: Bearer $BEARER_TOKEN" -d \
'{
  "add": [
    {"value": "cat has:media", "tag": "cats with media"},
    {"value": "cat has:media -grumpy", "tag": "happy cats with media"},
    {"value": "meme", "tag": "funny things"},
    {"value": "meme has:images"}
  ]
}'
curl -X POST 'https://api.twitter.com/labs/1/tweets/stream/filter/rules?dry_run=true' \
-H "Content-type: application/json" \
-H "Authorization: Bearer $BEARER_TOKEN" -d \
'{
  "add": [
    {"value": "cat has:media", "tag": "cats with media"},
    {"value": "cat has:media -grumpy", "tag": "happy cats with media"},
    {"value": "meme", "tag": "funny things"},
    {"value": "meme has:images"}
  ]
}'

Response

  • Create rules
  • Validate rules
{
    "data": [
        {
            "value": "meme",
            "tag": "funny things",
            "id": "1166895166390583299"
        },
        {
            "value": "cats has:media -grumpy",
            "tag": "happy cats with media",
            "id": "1166895166390583296"
        },
        {
            "value": "cat has:media",
            "tag": "cats with media",
            "id": "1166895166390583297"
        },
        {
            "value": "meme has:images",
            "id": "1166895166390583298"
        }

    ],
    "meta": {
        "sent": "2019-08-29T02:07:42.205Z",
        "summary": {
            "created": 4,
            "not_created": 0
        }
    }
}
{
    "data": [
        {
            "value": "meme",
            "tag": "funny things",
            "id": "1166895166390583299"
        },
        {
            "value": "cats has:media -grumpy",
            "tag": "happy cats with media",
            "id": "1166895166390583296"
        },
        {
            "value": "cat has:media",
            "tag": "cats with media",
            "id": "1166895166390583297"
        },
        {
            "value": "meme has:images",
            "id": "1166895166390583298"
        }

    ],
    "meta": {
        "sent": "2019-08-29T02:07:42.205Z",
        "summary": {
            "created": 4,
            "not_created": 0
        }
    }
}

Response fields

NameTypeDescription
idstringUnique identifier of this rule. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
valuestringThe rule text as submitted when creating the filter.
tagstringThe tag label as defined when creating the filter.
meta.sentdate (ISO 8601)The time when the request body was returned.
errorsobjectContains details about errors that affected any of the requested Tweets. See Status codes and error messages for more details.