{"type":"api","title":"List BGP updates","meta":{"id":"/apps/pubhub/media/000-v7-apis/a9d7d077fd3cd26af5968939669b4553e8957e87/ee87e69a-4f06-3347-b461-e56aaf2a2730","info":{"title":"BGP Updates API","version":"7.0.107","description":"Retrieve BGP updates observed by BGP monitors tracking prefixes in your ThousandEyes account group."},"security":[{"BearerAuth":[]}],"tags":[{"name":"BGP Updates"}],"openapi":"3.0.1","servers":[{"description":"ThousandEyes API production URL","url":"https://api.thousandeyes.com/v7"}],"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer authentication token"}}},"spec":{"tags":["BGP Updates"],"summary":"List BGP updates","operationId":"getBgpUpdates","description":"Retrieves a paginated list of BGP updates for prefixes tracked by the account group.\nWhen the `prefixes` filter is omitted, updates are returned for all prefixes currently tracked by the account group.\nUse the returned pagination links to request subsequent pages.\n","parameters":[{"name":"aid","in":"query","description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that you must be assigned to the target account group. Specifying this parameter without being assigned to the target account group will result in an error response.","required":false,"schema":{"type":"string","example":"1234"},"$$ref":"#/components/parameters/AccountGroupId"},{"name":"max","in":"query","required":false,"description":"Maximum number of BGP updates to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20}},{"name":"cursor","in":"query","example":null,"description":"(Optional) Opaque cursor used for pagination. Clients should use `next` value from `_links` instead of this parameter.","schema":{"type":"string","example":null},"$$ref":"#/components/parameters/PaginationCursor"},{"name":"expand","in":"query","required":false,"description":"Optional expansions. Pass `expand=monitor` to replace monitor IDs with full BGP monitor objects.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","description":"Expandable BGP data response sub-resources.","enum":["monitor"],"example":"monitor","$$ref":"#/components/schemas/BgpDataExpandOption"},"example":["monitor"]},"$$ref":"#/components/parameters/BgpDataExpand"},{"name":"startDate","in":"query","description":"Use with the `endDate` parameter. Include the complete time (hours, minutes, and seconds) in UTC time zone, following the ISO 8601 date-time format. See the example for reference. Please note that this parameter can't be used with `window`.","schema":{"type":"string","format":"date-time","example":"2022-07-17T22:00:54Z"},"$$ref":"#/components/parameters/StartDateParameter"},{"name":"endDate","in":"query","description":"Defaults to current time the request is made. Use with the `startDate` parameter. Include the complete time (hours, minutes, and seconds) in UTC time zone, following the ISO 8601 date-time format. See the example for reference. Please note that this parameter can't be used with `window`.","schema":{"type":"string","format":"date-time","example":"2022-07-18T22:00:54Z"},"$$ref":"#/components/parameters/EndDateParameter"},{"name":"prefixes","in":"query","required":false,"description":"Prefix CIDR filters. Repeat the parameter to filter by multiple prefixes.","style":"form","explode":true,"schema":{"type":"array","maxItems":1000,"items":{"type":"string"},"example":["192.0.2.0/24"]},"$$ref":"#/components/parameters/BgpPrefixes"},{"name":"originAses","in":"query","required":false,"description":"Origin AS filters. Repeat the parameter to filter by multiple ASNs.","style":"form","explode":true,"schema":{"type":"array","maxItems":1000,"items":{"type":"integer","format":"int64"},"example":[64512]},"$$ref":"#/components/parameters/BgpOriginAses"},{"name":"asPaths","in":"query","required":false,"description":"AS path filters, expressed as a space-separated list of ASNs. Repeat the parameter to filter by multiple AS paths.","style":"form","explode":true,"schema":{"type":"array","maxItems":1000,"items":{"type":"string"},"example":["64512 64513"]},"$$ref":"#/components/parameters/BgpAsPaths"},{"name":"rpkiStatuses","in":"query","required":false,"description":"RPKI status filters.","style":"form","explode":true,"schema":{"type":"array","maxItems":1000,"items":{"type":"string","description":"RPKI validation status for BGP data, using the validation states defined in RFC 6811, Section 2.","enum":["Valid","Invalid","NotFound","NotAvailable"],"example":"Valid","$$ref":"#/components/schemas/BgpRpkiStatus"}},"$$ref":"#/components/parameters/BgpRpkiStatuses"},{"name":"updateType","in":"query","required":false,"description":"BGP update type filters.","schema":{"type":"array","maxItems":1000,"items":{"type":"string","description":"Type of BGP update.","enum":["announcement","withdrawal","unspecified"],"example":"announcement","$$ref":"#/components/schemas/BgpUpdateType"}},"style":"form","explode":true},{"name":"monitorIds","in":"query","required":false,"description":"BGP monitor ID filters. Repeat the parameter to filter by multiple monitors. Get `monitorId` from the `/monitors` endpoint.","style":"form","explode":true,"schema":{"type":"array","maxItems":1000,"items":{"type":"string"},"example":["101"]},"$$ref":"#/components/parameters/BgpMonitorIds"},{"name":"communities","in":"query","required":false,"description":"BGP community filters. Repeat the parameter to filter by multiple communities.","style":"form","explode":true,"schema":{"type":"array","maxItems":1000,"items":{"type":"string"},"example":["64512:100"]},"$$ref":"#/components/parameters/BgpCommunities"}],"responses":{"200":{"description":"List of BGP updates.","content":{"application/hal+json":{"schema":{"type":"object","properties":{"updates":{"type":"array","items":{"type":"object","description":"BGP update observed by a BGP monitor.","properties":{"prefix":{"type":"string","description":"IP prefix in CIDR notation.","example":"192.0.2.0/24"},"originAs":{"type":"integer","format":"int64","nullable":true,"description":"Origin autonomous system (AS) number. Null when the update has no origin AS, including withdrawals.","example":64512},"asPath":{"type":"array","description":"AS path for the update. Empty when the update does not carry a path, including withdrawals.","items":{"type":"integer","format":"int64"},"example":[64512,64513]},"communities":{"type":"array","description":"BGP communities attached to the update. Empty when the update does not carry communities, including withdrawals.","items":{"type":"string"},"example":["64512:100"]},"rpkiStatus":{"type":"string","description":"RPKI validation status for the update, using the validation states defined in RFC 6811, Section 2. Returns NotAvailable when the update has no RPKI state, including withdrawals.","enum":["Valid","Invalid","NotFound","NotAvailable"],"$$ref":"#/components/schemas/BgpRpkiStatus","example":"Valid"},"updateType":{"type":"string","description":"Type of BGP update.","enum":["announcement","withdrawal","unspecified"],"$$ref":"#/components/schemas/BgpUpdateType","example":"announcement"},"monitorId":{"type":"string","description":"BGP monitor ID that observed the update. Returned by default and omitted when `expand=monitor` is requested.","example":"101"},"monitor":{"type":"object","properties":{"countryId":{"type":"string","description":"Country ID","example":"GB","readOnly":true},"monitorId":{"type":"string","description":"BGP monitor ID","example":"1234","readOnly":true},"ipAddress":{"type":"string","description":"IP address of the BGP monitor","example":"4.69.184.193"},"network":{"type":"string","description":"Name of the autonomous system in which the monitor is found","example":"Level 3 Communications, Inc. (AS 3356)"},"monitorType":{"type":"string","description":"Type of monitor","enum":["public","private"],"example":"public","$$ref":"#/components/schemas/MonitorType"},"monitorName":{"type":"string","description":"Display name of the BGP monitor","example":"Seattle, WA"},"asn":{"type":"integer","format":"int64","description":"Autonomous system number in which the monitor is found.","example":64512}},"$$ref":"#/components/schemas/BgpMonitor","description":"BGP monitor that observed the update. Returned when `expand=monitor` is requested and replaces `monitorId`.","example":{"monitorId":"101","ipAddress":"10.0.0.1","asn":64512,"monitorType":"private","monitorName":"Private monitor","countryId":"US"}},"timestamp":{"type":"string","format":"date-time","description":"Date and time when the update was observed.","example":"2024-05-31T16:08:37Z"}},"required":["prefix","originAs","asPath","communities","rpkiStatus","updateType","timestamp"],"oneOf":[{"required":["monitorId"]},{"required":["monitor"]}],"$$ref":"#/components/schemas/BgpUpdate"}},"_links":{"type":"object","description":"A links object containing pagination related link(s).","properties":{"previous":{"type":"object","description":"A hyperlink from the containing resource to a URI.","required":["href"],"properties":{"href":{"type":"string","description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id"},"templated":{"type":"boolean","description":"Should be true when the link object's \"href\" property is a URI template."},"type":{"type":"string","description":"Used as a hint to indicate the media type expected when dereferencing the target resource."},"deprecation":{"type":"string","description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation."},"name":{"type":"string","description":"Its value may be used as a secondary key for selecting link objects that share the same relation type."},"profile":{"type":"string","description":"A URI that hints about the profile of the target resource."},"title":{"type":"string","description":"Intended for labelling the link with a human-readable identifier"},"hreflang":{"type":"string","description":"Indicates the language of the target resource"}},"$$ref":"#/components/schemas/Link"},"next":{"type":"object","description":"A hyperlink from the containing resource to a URI.","required":["href"],"properties":{"href":{"type":"string","description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id"},"templated":{"type":"boolean","description":"Should be true when the link object's \"href\" property is a URI template."},"type":{"type":"string","description":"Used as a hint to indicate the media type expected when dereferencing the target resource."},"deprecation":{"type":"string","description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation."},"name":{"type":"string","description":"Its value may be used as a secondary key for selecting link objects that share the same relation type."},"profile":{"type":"string","description":"A URI that hints about the profile of the target resource."},"title":{"type":"string","description":"Intended for labelling the link with a human-readable identifier"},"hreflang":{"type":"string","description":"Indicates the language of the target resource"}},"$$ref":"#/components/schemas/Link"},"self":{"type":"object","description":"A hyperlink from the containing resource to a URI.","required":["href"],"properties":{"href":{"type":"string","description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id"},"templated":{"type":"boolean","description":"Should be true when the link object's \"href\" property is a URI template."},"type":{"type":"string","description":"Used as a hint to indicate the media type expected when dereferencing the target resource."},"deprecation":{"type":"string","description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation."},"name":{"type":"string","description":"Its value may be used as a secondary key for selecting link objects that share the same relation type."},"profile":{"type":"string","description":"A URI that hints about the profile of the target resource."},"title":{"type":"string","description":"Intended for labelling the link with a human-readable identifier"},"hreflang":{"type":"string","description":"Indicates the language of the target resource"}},"$$ref":"#/components/schemas/Link"}},"$$ref":"#/components/schemas/PaginationLinks"}},"$$ref":"#/components/schemas/BgpUpdates"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."},"errors":{"nullable":true,"type":"array","description":"(Optional) When multiple errors occur, the details for each error are listed.","items":{"type":"object","properties":{"code":{"type":"string","description":"(Optional) A unique error type/code that can be referenced in the documentation for further details."},"field":{"type":"string","description":"Identifies the field that triggered this particular error."},"message":{"type":"string","description":"A short, human-readable summary of the error."}},"$$ref":"#/components/schemas/ValidationErrorItem"}}},"$$ref":"#/components/schemas/ValidationError"},"example":{"type":"about:blank","title":"Request validation failed. There are invalid or missing fields","status":400,"detail":"Your request object contains invalid fields.","instance":"/v7","errors":[{"code":"AM-5432","field":"firstName","message":"firstName cannot have fancy characters"},{"code":"DASH-5622","field":"password","message":"Password cannot be blank"}]}}},"$$ref":"#/components/responses/400"},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_token"},"error_description":{"type":"string","example":"Invalid access token"}},"$$ref":"#/components/schemas/UnauthorizedError"}}},"$$ref":"#/components/responses/401"},"403":{"description":"Insufficient permissions to query endpoint","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"}}},"$$ref":"#/components/responses/403"},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"URI Resource Not Found","status":404,"detail":"Details explaining if the 404 error is related to an invalid URI or a wrong ID","instance":"/v7"}}},"$$ref":"#/components/responses/404"},"429":{"description":"Exhausted rate limit for the organization","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"}}},"$$ref":"#/components/responses/429"},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"Internal server error","status":500,"detail":"Optional detail about the internal error message.","instance":"/v7"}}},"$$ref":"#/components/responses/500"},"502":{"description":"Bad Gateway","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"}}},"$$ref":"#/components/responses/502"}},"__originalOperationId":"getBgpUpdates","security":[{"BearerAuth":[]}],"method":"get","path":"/bgp/updates"}}