# url – return contents from URL

- Synopsis
- Parameters
- Examples
- Return Values
- Status

## Synopsis

- Returns the content of the URL requested to be used as data in play.

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
_terms - |  |  | urls to query
headers dictionary added in 2.9 | Default: {} |  | HTTP request headers
password string added in 2.8 |  |  | Password to use for HTTP authentication.
split_lines boolean | Default: "yes" |  | Flag to control if content is returned as a list of lines or as a single text blob
use_proxy boolean | Default: "yes" |  | Flag to control if the lookup will observe HTTP proxy environment variables when present.
username string added in 2.8 |  |  | Username to use for HTTP authentication.
validate_certs boolean | Default: "yes" |  | Flag to control SSL certificate validation

## Examples

    - name: url lookup splits lines by default
      debug: msg="{{item}}"
      loop: "{{ lookup('url', 'https://github.com/gremlin.keys', wantlist=True) }}"

    - name: display ip ranges
      debug: msg="{{ lookup('url', 'https://ip-ranges.amazonaws.com/ip-ranges.json', split_lines=False) }}"

    - name: url lookup using authentication
      debug: msg="{{ lookup('url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2') }}"

    - name: url lookup using headers
      debug: msg="{{ lookup('url', 'https://some.private.site.com/api/service', headers={'header1':'value1', 'header2':'value2'} ) }}"

## Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key | Returned | Description
--- | --- | ---
_list - |  | list of list of lines or content of url(s)

## Status

- This lookup is not guaranteed to have a backwards compatible interface. [preview]
- This lookup is maintained by the Ansible Community. [community]

### Authors

- Brian Coca (@bcoca)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.