POST /2/tweets/search/stream/rules

Add or delete rules to your stream.

To create one or more rules, submit an add JSON body with an array of rules and operators. Similarly, to delete one or more rules, submit a delete JSON body with an array of list of existing rule IDs.



Endpoint URL

https://api.twitter.com/2/tweets/search/stream/rules

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

Rate limit

450 requests per 15-minute window (app auth)

Learn more about rate limits.



Query parameters

NameTypeDescription
dry_run
 Optional 
booleanSet 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

NameTypeDescription
add
 Required 
arraySpecifies the operation you want to perform on the rules.
add.tag
 Optional 
stringThe 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.
add.value
 Required 
stringThe rule text. If you are using a Standard Project at the Basic access level, you can use the basic set of operators, can submit up to 25 concurrent rules, and can submit rules up to 512 characters long. If you are using an Academic Research Project at the Basic access level, you can use all available operators, can submit up to 1,000 concurrent rules, and can submit rules up to 1,024 characters long.
delete
 Required 
objectSpecifies the operation you want to perform on the rules.
delete.ids
 Required 
arrayArray of rule IDs, each one representing a rule already active in your stream. IDs must be submitted as strings.


Example requests

  • Add rules
  • Validate rules
  • Delete rules
      curl -X POST 'https://api.twitter.com/2/tweets/search/stream/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/2/tweets/search/stream/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"}
  ]
}'

    
      curl -X POST 'https://api.twitter.com/2/tweets/search/stream/rules' 
  -H "Content-type: application/json" 
  -H "Authorization: Bearer $BEARER_TOKEN" -d 
  '{
    "delete": {
      "ids": [
        "1165037377523306498",
        "1165037377523306499"
      ]
    }
  }'

    

Example responses

  • Create rules
  • Validate rules
  • Success
      {
  "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
    }
  }
}
    
      {
  "meta": {
    "sent": "2019-08-29T01:48:54.633Z",
    "summary": {
      "deleted": 1,
      "not_deleted": 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 rule.
tagstringThe tag label as defined when creating the rule.
meta.sentnumberThe 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.
Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.